If an install script fails, this will help:
- In the HexOS UI, check your notifications for an app install failure
- Click the notification to view the error message
¶ 2. Check hook failures (V5 and V6 scripts)
If your install script uses lifecycle hooks, hook tasks appear as children of the main install task in the HexOS activity center:
- Open the Activity Center (bell icon) in the HexOS UI
- Expand the install task to see individual hook steps
- Each hook shows its checkpoints and current status
- If a hook failed:
- Click View Details to see structured error context (endpoint, status code, etc.)
- Click Retry to re-run the hook from the failed checkpoint
- Click Skip to skip the hook and continue (if allowed)
Common hook failure causes:
- App not ready — the container hasn't finished starting. Increase the hook's
timeout or add a longer delay in waitForApp()
- Network unreachable — the hook can't reach the app's HTTP endpoint. Check that the port is correct and the app binds to
0.0.0.0
- OAuth timeout — the user didn't complete the OAuth flow within the time limit. Retry the hook to get a fresh OAuth prompt
- Missing input — a required hook input wasn't provided. Check your
inputs declarations
- Navigate to the TrueNAS web interface (e.g.,
https://10.0.1.13)
- Go to the Jobs section to view the installation job details
- Look for error messages in the detailed job output
Option A: TrueNAS Apps UI (if container is running)
- Navigate to
https://10.0.1.13/ui/apps/installed
- Click on the app, under Workloads > Containers, click the View Logs button
- Review container logs for startup errors
Option B: Shell Access (if container stopped or logs unavailable)
- Navigate to
https://10.0.1.13/ui/system/shell
- Run
sudo docker container list -a to find your container
- Copy the container ID
- Run
sudo docker logs <container_id> to view detailed logs
¶ 5. Common issues and solutions
- Symptom: App fails to start, logs show permission denied errors
- Solution: Add the
owner field to the relevant entry in ensure_directories_exists with the correct TrueNAS user and group (e.g., { "user": "netdata", "group": "docker" })
- Example: PostgreSQL data directories typically require
"owner": { "user": "netdata", "group": "docker" }
- Symptom: App fails during installation, "directory not found" errors
- Solution: Ensure all required paths are listed in
ensure_directories_exists
- Symptom: TrueNAS job fails with validation errors
- Solution: Compare your
app_values structure with the official TrueNAS app schema
- Symptom: Hook task shows
AWAITING_RETRY with an error message
- Solution: Check the error context details for the specific failure. Common fixes:
- Ensure the
entrypoint function name matches what's exported in your script
- Verify the app's API endpoint path is correct
- Confirm all
await keywords are present on async calls
The current debugging workflow requires accessing the TrueNAS interface directly; in the future we plan to expose more of this debugging workflow within HexOS's UI.