Troubleshoot common Nora issues
Solutions for the most common Nora installation, agent deployment, LLM provider, authentication, and dashboard loading problems you may encounter.If something is not working as expected, this page covers the most frequent problems operators encounter when self-hosting Nora and explains exactly what to check or change. Work through the category that matches your situation, and use the log commands below to gather more context when the cause is unclear.


Installation issues
Installation issues
Docker not foundThe Nora setup script can install Docker, Docker Compose, and Git for you if they are missing. Run the installer and follow the prompts:If you prefer to install Docker manually, follow the official Docker installation guide for your operating system, then re-run setup.
Port 8080 or 4100 already in useIn local mode, the installer checks the browser port and backend API port before startup. IfRestart the stack after saving the change:
First signup fails withIf you want to keep existing local data, restore
Stack fails to startCheck the backend API logs for the error that caused the failure:Common causes include a missing or malformed Run that command twice — once for
Port 8080 or 4100 already in useIn local mode, the installer checks the browser port and backend API port before startup. If
8080 is busy, accept the suggested web port such as 8081. If 127.0.0.1:4100 is busy, accept the suggested backend API port such as 4101.If you edit .env manually, use these variables:First signup fails with
password authentication failed for user "nora"This means the backend cannot authenticate to Postgres. The usual cause is a local reconfigure where the Docker Postgres volume was preserved but .env now contains a different DB_PASSWORD than the one used when the volume was initialized.If you want a clean local install, remove the compose volumes and rerun setup:DB_PASSWORD from the newest .env.backup-* file:Stack fails to startCheck the backend API logs for the error that caused the failure:
JWT_SECRET, a missing ENCRYPTION_KEY, or a database connection failure. Verify that your .env file contains valid 64-character hex values for both required secrets:JWT_SECRET and once for ENCRYPTION_KEY.Agent deployment issues
Agent deployment issues
Agent stuck in “queued” stateA queued agent that never transitions to running usually means the provisioner cannot reach the Docker socket. Check the backend logs for provisioning errors:Verify that the Docker socket is mounted correctly in your
Agent in “error” stateIf an agent lands in the error state after deployment, use the Redeploy button on the agent detail page to attempt a fresh deployment. If the error persists, inspect the backend logs to identify what failed during provisioning:
Kubernetes says
NemoClaw sandbox fails to startNemoClaw is disabled by default. To enable it, addRestart the stack after making these changes. If NemoClaw still fails, confirm that your NVIDIA API key is active and has access to the NVIDIA NIM endpoints Nora uses.For Kubernetes, also confirm
docker-compose.yml and that the user running the backend has permission to access it.Agent in “error” stateIf an agent lands in the error state after deployment, use the Redeploy button on the agent detail page to attempt a fresh deployment. If the error persists, inspect the backend logs to identify what failed during provisioning:
Kubernetes says
deployments.apps "<agent>" not foundThis means Nora has an agent record but the Kubernetes Deployment no longer exists in the registered cluster/namespace. It can happen after manual kubectl delete, a failed stale start, or a registry namespace mismatch. Use Redeploy on the agent detail page to recreate the Deployment, Service, and bootstrap ConfigMap from the saved Nora agent settings.If redeploy also fails, open Admin -> Kubernetes, run Test on the cluster row, and confirm the OpenClaw and Hermes namespaces match where you expect agents to run.NemoClaw sandbox fails to startNemoClaw is disabled by default. To enable it, add
nemoclaw to the enabled sandbox profiles and provide a valid NVIDIA API key either as a user provider key in Settings or as a platform fallback in .env:NEMOCLAW_SANDBOX_IMAGE points to an image your nodes can pull. The default is Nora’s GHCR image; offline clusters must preload nora-nemoclaw-agent:local and override the env var.Remote Docker issues
Remote Docker issues
Host says Connected, but deployment failsThe Remote Hosts Test action runs only from Verify the worker can reach the SSH address, the remote host has registry/provider egress and
enough capacity, and the configured gateway address plus allocated
Host is missing from the Deploy pageConfirm the host is enabled, configured, and its latest manual test succeeded. A personal host requires ownership or an
Agent or container still exists after host access is revokedThis is expected. Unsharing or removing a platform access grant changes authorization only. It does not stop, move, delete, or rebalance existing containers. After the agent owner loses their final qualifying path, Nora denies active operations—including new/queued deployment work, start/restart, live runtime access, logs, terminal, backup capture, non-stop scheduled actions, and ClawHub—and closes rechecked active streams. Live status and telemetry collection stops. The stored agent record, lifecycle status, and previously collected telemetry history can remain visible but are no longer live. Stop, whether manual or scheduled, and Delete remain available for cleanup only while the registration still retains the previously trusted SSH host-key pin.Follow the documented drain procedure: back up or export the agent, create and validate a replacement elsewhere, delete the old Remote Docker agent, and then unshare. If unshare already happened, use the retained Stop or Delete action. If the pin was reset or lost, Nora fails closed and keeps the agent record; verify the host out of band, re-run Test where possible, or remove the runtime manually. For an urgent incident, also close direct network access to the published ports and rotate the SSH credential.
Remote host cannot be deletedNora returns
Remote host key changed after an intentional rebuild or rotationFirst verify the replacement SSH host key through the machine console or another trusted out-of-band channel. Then open the host’s owning surface—App -> Remote Hosts for a personal host or Admin -> Remote Hosts for a platform host—choose Reset SSH pin, type the exact host label or id, and confirm. Nora clears the pin and previous Test state without changing the stored credentials. Run Test immediately; deployments and active use remain blocked until the new key is captured and pinned. If you cannot explain and independently verify the key change, do not reset it.
A personal host is read-only in AdminThis is intentional. Platform admins manage platform hosts under Admin -> Remote Hosts. A personal host remains managed by its user owner under App -> Remote Hosts; its Admin fleet row exposes only masked inventory metadata. Do not copy its credentials into a new platform record to work around the ownership boundary.
backend-api. It applies a 10-second overall
SSH/Docker probe deadline and runs docker version as the registered user. It does not test
worker-provisioner, image pulls, host capacity, published-port routing, runtime readiness,
lifecycle actions, or backups. The successful result has no expiry or background refresh.Re-run Test, then inspect the worker and API logs while deploying a disposable agent:19000-19999 ports are
reachable from Nora.Host is missing from the Deploy pageConfirm the host is enabled, configured, and its latest manual test succeeded. A personal host requires ownership or an
editor+ workspace grant. A platform host permits platform admins,
all accounts when enabled, directly granted users, matching user groups, and editor+ members of
a granted workspace. Workspace viewers see the host but cannot deploy. The current dashboard
injects Remote Docker targets into OpenClaw’s picker only; Hermes Remote Docker uses the experimental
advanced API path.Agent or container still exists after host access is revokedThis is expected. Unsharing or removing a platform access grant changes authorization only. It does not stop, move, delete, or rebalance existing containers. After the agent owner loses their final qualifying path, Nora denies active operations—including new/queued deployment work, start/restart, live runtime access, logs, terminal, backup capture, non-stop scheduled actions, and ClawHub—and closes rechecked active streams. Live status and telemetry collection stops. The stored agent record, lifecycle status, and previously collected telemetry history can remain visible but are no longer live. Stop, whether manual or scheduled, and Delete remain available for cleanup only while the registration still retains the previously trusted SSH host-key pin.Follow the documented drain procedure: back up or export the agent, create and validate a replacement elsewhere, delete the old Remote Docker agent, and then unshare. If unshare already happened, use the retained Stop or Delete action. If the pin was reset or lost, Nora fails closed and keeps the agent record; verify the host out of band, re-run Test where possible, or remove the runtime manually. For an urgent incident, also close direct network access to the published ports and rotate the SSH credential.
Remote host cannot be deletedNora returns
409 while any non-deleted agent still references the host’s remote:<id> target.
Migrate or delete those agents first. Unsharing a workspace does not remove the references.After deletion succeeds, Nora permanently reserves the personal or platform host id. This
prevents a different machine and credential from later inheriting the old remote:<id> target.
If you need to register a replacement, choose a new label/id.See Remote Docker setup and limitations for
host compatibility, test scope, firewall rules, capacity limits, and sharing semantics.Remote host key changed after an intentional rebuild or rotationFirst verify the replacement SSH host key through the machine console or another trusted out-of-band channel. Then open the host’s owning surface—App -> Remote Hosts for a personal host or Admin -> Remote Hosts for a platform host—choose Reset SSH pin, type the exact host label or id, and confirm. Nora clears the pin and previous Test state without changing the stored credentials. Run Test immediately; deployments and active use remain blocked until the new key is captured and pinned. If you cannot explain and independently verify the key change, do not reset it.
A personal host is read-only in AdminThis is intentional. Platform admins manage platform hosts under Admin -> Remote Hosts. A personal host remains managed by its user owner under App -> Remote Hosts; its Admin fleet row exposes only masked inventory metadata. Do not copy its credentials into a new platform record to work around the ownership boundary.
LLM provider issues
LLM provider issues
API keys are not reaching the agentProvider keys saved in Settings are not automatically pushed to running agents. After adding or updating a key, open the agent detail page and click the Sync button to inject the current keys into the running runtime.
Invalid API key errors from the agentIf the agent reports that a key is invalid or unauthorized, verify the key directly with the provider before troubleshooting Nora. Keys are stored using AES-256-GCM encryption and are never returned in API responses, so the value Nora holds is the exact value you entered. If the key itself is correct, confirm that you selected the right provider in Settings.
Invalid API key errors from the agentIf the agent reports that a key is invalid or unauthorized, verify the key directly with the provider before troubleshooting Nora. Keys are stored using AES-256-GCM encryption and are never returned in API responses, so the value Nora holds is the exact value you entered. If the key itself is correct, confirm that you selected the right provider in Settings.
Authentication issues
Authentication issues
Cannot log inThe most common login failure in self-hosted deployments is a mismatch between After correcting the value, restart the stack:
OAuth login button is missing or disabledOAuth login (Google, GitHub) is disabled by default. To enable it, set the following variable and provide your OAuth client credentials in
NEXTAUTH_URL and the URL you are actually using to access Nora. The value in your .env file must exactly match the origin your browser is loading:OAuth login button is missing or disabledOAuth login (Google, GitHub) is disabled by default. To enable it, set the following variable and provide your OAuth client credentials in
.env:You only need to set credentials for the OAuth providers you want to enable. Leave the others blank.
Dashboard not loading
Dashboard not loading
If the dashboard returns a CORS error or a blank page, your Restart the stack after saving the change:To confirm the backend is healthy, check its logs directly:
CORS_ORIGINS value likely does not include the origin your browser is using. Add your origin to the variable as a comma-separated value:Getting more help
If you cannot resolve your issue with the steps above, the following resources are available:- Reproducible bugs — open an issue at github.com/solomon2773/nora/issues
- Setup and rollout questions — start a discussion at github.com/solomon2773/nora/discussions
- Enterprise and managed paths — see nora.solomontsao.com/pricing
.env file contents.
