Back to Articles
TrueNAS7 min read
TrueNAS Apps Not Working? The Complete 2026 Fix Guide
Step-by-step troubleshooting guide for TrueNAS Scale apps that won't start, catalogs that fail to load, and Kubernetes initialization errors in 2026.
Step-by-step troubleshooting guide for TrueNAS Scale apps that won't start, catalogs that fail to load, and Kubernetes initialization errors in 2026.
If you run TrueNAS Scale, you have almost certainly encountered a moment where your Apps tab shows nothing, Docker refuses to start, or the catalog suddenly goes blank. These failures are some of the most common pain points in the TrueNAS community, and they can strike after an update, a reboot, or seemingly out of nowhere. This guide compiles the verified fixes from official TrueNAS documentation and community troubleshooting threads so you can get your apps back online fast.
TrueNAS Scale 24.10 (Electric Eel) and later versions run applications inside Docker containers using Docker Compose. Prior to 24.10, the backend used Kubernetes (k3s) — that architecture is no longer relevant for current installs. When Docker fails to initialize, or when the underlying pool configuration is misaligned, apps simply will not start. Based on community reports from 2024 through early 2026, the most frequent causes include:
Before diving into fixes, make sure you have:
The most common fix for a non-initializing Docker service is to unset and then re-set the Apps pool. This forces the system to regenerate the service configuration.
1. Go to Apps and click the Configuration dropdown in the top right.
2. Click Unset Pool. Confirm the action when prompted. This stops the apps service.
3. Click the Configuration dropdown again and select Choose Pool.
4. Select the same pool you used before (or a new dedicated pool) and click Save.
5. Wait for the Docker service to reinitialize. This can take several minutes.
Note: Unsetting the pool does not delete your applications or their data. According to the TrueNAS documentation, this operation often fixes failed deployments without data loss.
If the pool is not listed or if the web UI hangs, try a full system reboot first, then repeat the steps above.
Sometimes the Docker service configuration becomes corrupted or stuck. Reapplying the settings can clear the stalled state.
1. Navigate to Apps > Configuration > Settings.
2. Make a minor change — for example, toggle Install NVIDIA Drivers off if it is on (or vice versa), then click Save.
3. If no obvious toggle is available, change the Address Pools base network slightly and then revert it. Saving the settings forces a clean service restart.
4. After saving, monitor the Apps dashboard. The status should change from the error state to Apps Service Running within a few minutes.
Community tip: Multiple forum threads confirm that toggling the NVIDIA driver setting off and saving resolves the "Failed to start docker service" error on systems where GPU support was recently changed.
If your Discover Apps page is empty or shows an error about failing to clone a repository, the local catalog directory may be corrupted.
A typical error looks like this:
[EFAULT] Failed to clone 'GitHub - truenas/apps' repository at '/mnt/.ix-apps/truenas_catalog'1. Go to Apps > Configuration > Settings and look for the catalog refresh option.
2. Alternatively, go to Apps and if a Manage Catalogs or Refresh Catalog button is visible, click it. This triggers a fresh clone of the official TrueNAS apps repository.
3. If the refresh option is not visible in the UI, SSH into your TrueNAS server.
4. Remove the corrupted catalog directory under /mnt/.ix-apps/:
[command not verified — check official TrueNAS documentation for exact path and command]5. Return to the web UI and trigger a catalog refresh.
If the clone continues to fail, check your network connectivity and DNS settings. Errors like "early EOF" or "index-pack failed" typically indicate a transient network issue or memory pressure during the clone.
When the above steps do not resolve the issue, the system logs can pinpoint the exact failure.
From the TrueNAS web interface, go to System Settings > Advanced > Save Debug. Download the debug archive and look for logs related to docker, apps, or ix-apps.
If you have SSH access, you can inspect the Docker service directly:
systemctl status dockerA stopped or failed Docker service confirms the service needs attention. Common log patterns to look for:
Failed to start docker for Applications: Docker service could not be startedError In Apps ServiceApplications are not runningjournalctl -u docker --no-pager | tail -50This shows the last 50 lines of Docker service logs and usually reveals the root cause — such as a storage issue, a conflicting network configuration, or a failed image pull.
If nothing else works, a full reset of the applications environment is the nuclear option. This will destroy all deployed applications and their data, so proceed only if you have backups or are willing to reconfigure everything.
1. Go to Apps > Configuration > Unset Pool and confirm.
2. SSH into your server. The apps data is stored in a hidden dataset mounted at /mnt/.ix-apps. Remove it carefully:
[command not verified — check official TrueNAS documentation before proceeding]3. Return to the web UI and go to Apps > Configuration > Choose Pool.
4. Select the pool again and click Save.
5. Redeploy your applications from scratch.
Warning: This method deletes all application state, including persistent volumes and configuration. Only use this as a last resort and only after backing up any data stored in host path mounts.
Users who updated to newer versions of TrueNAS Scale (such as 25.04 Fangtooth or 25.10) have reported that apps disappeared and the catalog went empty. This is often caused by a change in how the system manages the catalog repository or by the migration from the older app infrastructure.
truenas.com/docs, as major releases sometimes require manual steps after upgrade.Avoid future app failures with these best practices:
TrueNAS Scale apps can be finicky, but almost every failure mode has a known fix. Start with the simplest solution — verifying and reassigning the Apps pool via Apps > Configuration > Choose Pool — and work your way up to the full reset if needed. The TrueNAS community forums at forums.truenas.com and the official documentation hub at truenas.com/docs remain the best resources for version-specific issues, especially after major upgrades.
If this guide helped you get your apps back online, bookmark it for the next time the catalog goes blank or Docker refuses to initialize. In the world of self-hosted homelabs, a little troubleshooting knowledge goes a long way.