Skip to main content

​
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. Account event log — recent lifecycle, deploy, and error events for the operator When digging into a specific failure, scope the log view to errors only — the same surface filters by event type and severity: Event log filtered to errors — exact failure events with metadata
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:
curl -fsSL https://raw.githubusercontent.com/solomon2773/nora/master/setup.sh | bash
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. 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:
NGINX_HTTP_PORT=9090
NEXTAUTH_URL=http://localhost:9090
CORS_ORIGINS=http://localhost:9090
BACKEND_API_PORT=4101
Restart the stack after saving the change:
docker compose down && docker compose up -d
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:
cd ~/nora
docker compose down -v --remove-orphans
curl -fsSL https://raw.githubusercontent.com/solomon2773/nora/master/setup.sh | bash
If you want to keep existing local data, restore DB_PASSWORD from the newest .env.backup-* file:
cd ~/nora

python3 - <<'PY'
from pathlib import Path

backups = sorted(Path(".").glob(".env.backup-*"), key=lambda p: p.stat().st_mtime, reverse=True)
if not backups:
    raise SystemExit("No .env.backup-* file found")

old = None
for line in backups[0].read_text().splitlines():
    if line.startswith("DB_PASSWORD="):
        old = line.split("=", 1)[1]
        break

if not old:
    raise SystemExit(f"No DB_PASSWORD found in {backups[0]}")

env = Path(".env")
lines = env.read_text().splitlines()
for i, line in enumerate(lines):
    if line.startswith("DB_PASSWORD="):
        lines[i] = "DB_PASSWORD=" + old
        break
else:
    lines.append("DB_PASSWORD=" + old)

env.write_text("\n".join(lines) + "\n")
print(f"Restored DB_PASSWORD from {backups[0]}")
PY

docker compose up -d --build
Stack fails to startCheck the backend API logs for the error that caused the failure:
docker compose logs -f backend-api
Common causes include a missing or malformed 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:
openssl rand -hex 32
Run that command twice — once for JWT_SECRET and once for ENCRYPTION_KEY.
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:
docker compose logs -f backend-api
Verify that the Docker socket is mounted correctly in your 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:
docker compose logs -f backend-api
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 in your .env file:
ENABLED_SANDBOX_PROFILES=standard,nemoclaw
NVIDIA_API_KEY=your-nvidia-api-key
Restart 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.
Do not paste your NVIDIA API key into GitHub Issues or Discussions. Share only masked or redacted values when asking for help.
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.
If you just deployed a new agent, always sync your provider keys before testing chat to avoid “no provider configured” errors.
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.
Cannot log inThe most common login failure in self-hosted deployments is a mismatch between 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:
# Local mode
NEXTAUTH_URL=http://localhost:8080

# Public domain mode
NEXTAUTH_URL=https://app.example.com
After correcting the value, restart the stack:
docker compose down && docker compose up -d
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:
OAUTH_LOGIN_ENABLED=true
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
You only need to set credentials for the OAuth providers you want to enable. Leave the others blank.
If the dashboard returns a CORS error or a blank page, your CORS_ORIGINS value likely does not include the origin your browser is using. Add your origin to the variable as a comma-separated value:
# Single origin
CORS_ORIGINS=http://localhost:8080

# Multiple origins
CORS_ORIGINS=https://app.example.com,http://localhost:8080
Restart the stack after saving the change:
docker compose down && docker compose up -d
To confirm the backend is healthy, check its logs directly:
docker compose logs -f backend-api

​
Getting more help

If you cannot resolve your issue with the steps above, the following resources are available: When asking for help, include your deployment mode (self-hosted, rollout-help, or hosted), your OS, which setup script you used, and any relevant log output. Do not include secrets, API keys, or .env file contents.