Operations

Troubleshooting

Resolve common errors by symptom.

The interface does not start

Check docker compose ps and the complete startup logs. Verify port availability and data access for the actual runtime UID:GID. No explicit environment secret is required on a fresh installation. A rebuild cannot fix host-folder ACLs.

An integration works in the browser but not in NasDash

Test from the container. Replace localhost with the Compose service name, a private IP, or a routable DNS name. Check the firewall and routing.

Docker displays 403 or an action fails

Check the connection type first. For Portainer or Dockhand, verify the API key and its environment permissions. For an HTTP API or socket proxy, check route and method permissions such as CONTAINERS, POST and DELETE. For a Unix socket, check the mounted path and runtime user's access. Do not enable unrelated capabilities.

Glances returns HTML

NasDash expects JSON on the /api/<version>/all route. Verify that the Glances web server, rather than a proxy authentication page, is responding.

Proxmox displays 401/403

Check the full Token ID, the secret, the exact node name, and the read role on the correct path. Rotate a compromised secret instead of copying it into logs.

CSS makes the interface unusable

Add ?safe-css=1 to the URL, open developer settings, fix or clear the CSS, then reload without the parameter. See Custom CSS.

Viewers see too much or too little

Check secret category visibility and the user’s tab/widget allowlists. Empty lists mean unrestricted access within that list. Permission changes revoke existing sessions, so log in again. See the server access matrix.

Synology and data-folder permissions

Images from version 0.2.2 onward check access before startup and report the actual runtime UID:GID if data, logos or existing files are inaccessible. Correct the folder permissions and recreate the container. Linux Docker UID/GID tests do not substitute for real DSM validation.

Synology and data-folder permissions

Missing setup code or lost access

The setup code appears once, after the administrator password hash is saved and before the server is ready. Inspect the complete startup logs, including warnings/stderr. Restarting or rebuilding does not print a new code. If NASDASH_ADMIN_PASSWORD was set when the account was created, use that first password instead.

For a lost code or password, Forgot it? on the regular sign-in screen shows the offline recovery command. Back up the data and stop NasDash before running it; keep the same data mount and UID/GID. See setup code and offline recovery.

Monitoring errors and certificates

Timeouts, refused connections and unreachable hosts are retryable warnings. Authentication 401/403, missing endpoint 404 and malformed JSON are configuration errors. For self-signed certificates, enable acceptance explicitly on the selected connection only; never disable TLS verification globally. See Glances endpoint diagnostics and Proxmox token/TLS settings.

For feedback, include integration type, NasDash version/image digest, redacted URL, status/error code, frequency and relevant remote-service logs. Remove setup codes, startup passwords, tokens, cookies, keys and private data before using the issue chooser. Do not publish a data directory.

If saved configuration is damaged, NasDash preserves the damaged file and recovers with private access; it does not publish the instance as part of recovery. Stop the service, keep the damaged copy and restore a verified complete backup or repair the configuration before continuing. Configuration updates stage related files together and roll back reported write failures; this is not a guarantee against power loss. Keep backups on separate storage.