Troubleshooting

Common issues and how to fix them. If your problem isn't listed here, run nordon doctor for automatic diagnostics.

Daemon not running

Symptom: Commands fail with "cannot connect to daemon" or "connection refused".

Likely cause: The NORDON daemon is not running.

Fix:

Check the daemon status:
```
nordon status
```
Start the daemon:
```
nordond &
```
To make it start automatically, install it as a service:
```
nordon service install
```

Config not found

Symptom: You see "config file not found" or "no config detected" when running commands.

Likely cause: NORDON has not been initialized on this machine.

Fix:

Run the init command to create your config and data directories:
```
nordon init
```
Verify the config was created:
```
nordon doctor
```

Repo not linked

Symptom: You see "repository not linked" or memories are not being tracked for your project.

Likely cause: You have not linked the current repository to NORDON.

Fix:

Navigate to your project directory and link it:
```
cd /path/to/your/project
nordon link-repo
```
Verify the link:
```
nordon status
```

Make sure you are in a directory with a git repository. NORDON uses the git remote URL to identify projects.

No memories appearing

Symptom: You have been using NORDON but no memories show up when you search.

Likely cause: Memories are created from events captured during your coding sessions. It takes a few sessions before memories are generated.

Fix:

Check that events are being captured:
```
nordon logs --limit 10
```
If no events are showing, verify your Claude Code hooks are configured correctly (see the hooks guide).
If events exist but no memories, give it more time. NORDON needs enough context from multiple tool uses to create meaningful memories.

Injection is empty

Symptom: nordon inject --preview returns nothing or very little context.

Likely cause: There are not enough memories yet, or the context budget is too small.

Fix:

Check how many memories exist:
```
nordon memories search ""
```
If there are few or no memories, use NORDON for a few more sessions. Memories build up over time.
Make sure the daemon is running and hooks are configured. Events need to flow before memories can be created.

Permission denied

Symptom: npm install fails with "EACCES" or "permission denied" errors.

Likely cause: npm does not have permission to install global packages in the default location.

Fix:

On macOS/Linux, use the --global flag with proper permissions:
```
sudo npm install -g @sodasoft/nordon-cli
```

Or configure npm to use a different directory for global packages:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add ~/.npm-global/bin to your PATH

On Windows, run your terminal as Administrator or use nvm to manage Node installations.

Port already in use

Symptom: The daemon fails to start with "address already in use" or "EADDRINUSE".

Likely cause: Another process is using port 7533, or a previous daemon instance did not shut down cleanly.

Fix:

Change the port in your config file:

# ~/.config/nordon/config.toml
api_port = 9000

Start the daemon on the new port:
```
nordond --port 9000 &
```

Update the CLI to use the new port:

export NORDON_API_URL=http://127.0.0.1:9000

License activation failed

Symptom: nordon plan activate fails with "invalid key" or "activation failed".

Likely cause: The license key may be incorrect, expired, or the daemon is not running.

Fix:

Double-check your license key. Copy it directly from the confirmation email to avoid typos.
Make sure the daemon is running:
```
nordon status
```
Try activating again:
```
nordon plan activate <your-license-key>
```
If it still fails, check your account status:
```
nordon account status
```

Can't connect to daemon

Symptom: CLI commands hang or return "connection timed out".

Likely cause: The daemon is not reachable. This could be a port mismatch or a firewall blocking the connection.

Fix:

Check that the daemon is running:
```
nordon status
```
Make sure the port matches. If you changed the port in the config, the CLI needs to know:
```
export NORDON_API_URL=http://127.0.0.1:7533
```
Check if a firewall is blocking localhost connections. NORDON only uses 127.0.0.1 (localhost) — it does not need internet access to function.

Restart the daemon:

# Stop any existing instances
nordon service uninstall
# Start fresh
nordond &

Claude Code hooks not working

Symptom: Events are not being captured during Claude Code sessions.

Likely cause: The hooks are not configured in the right file, or the JSON is malformed.

Fix:

Verify the settings file path:
- macOS / Linux: ~/.claude/settings.json
- Windows: %USERPROFILE%\.claude\settings.json

Open the file and check that the JSON is valid. A missing comma or bracket will break it. The hooks section should look like:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "command": "nordon hook post-tool \"$TOOL_NAME\"",
      "timeout": 5000
    }],
    "Stop": [{
      "matcher": "",
      "command": "nordon hook session-end",
      "timeout": 10000
    }]
  }
}

Make sure the daemon is running:
```
nordon status
```
Restart Claude Code to pick up the updated settings.
After a session, check if events are flowing:
```
nordon logs --limit 5
```

Still stuck?

Run diagnostics and check the output for clues:

nordon doctor
nordon logs --limit 50

If the issue persists, check out these resources:

Configuration·Guides·CLI Reference

Troubleshooting

Common issues and how to fix them. If your problem isn't listed here, run nordon doctor for automatic diagnostics.

Daemon not running

Symptom: Commands fail with "cannot connect to daemon" or "connection refused".

Likely cause: The NORDON daemon is not running.

Fix:

Check the daemon status:
```
nordon status
```
Start the daemon:
```
nordond &
```
To make it start automatically, install it as a service:
```
nordon service install
```

Config not found

Symptom: You see "config file not found" or "no config detected" when running commands.

Likely cause: NORDON has not been initialized on this machine.

Fix:

Run the init command to create your config and data directories:
```
nordon init
```
Verify the config was created:
```
nordon doctor
```

Repo not linked

Symptom: You see "repository not linked" or memories are not being tracked for your project.

Likely cause: You have not linked the current repository to NORDON.

Fix:

Navigate to your project directory and link it:
```
cd /path/to/your/project
nordon link-repo
```
Verify the link:
```
nordon status
```

Make sure you are in a directory with a git repository. NORDON uses the git remote URL to identify projects.

No memories appearing

Symptom: You have been using NORDON but no memories show up when you search.

Likely cause: Memories are created from events captured during your coding sessions. It takes a few sessions before memories are generated.

Fix:

Check that events are being captured:
```
nordon logs --limit 10
```
If no events are showing, verify your Claude Code hooks are configured correctly (see the hooks guide).
If events exist but no memories, give it more time. NORDON needs enough context from multiple tool uses to create meaningful memories.

Injection is empty

Symptom: nordon inject --preview returns nothing or very little context.

Likely cause: There are not enough memories yet, or the context budget is too small.

Fix:

Check how many memories exist:
```
nordon memories search ""
```
If there are few or no memories, use NORDON for a few more sessions. Memories build up over time.
Make sure the daemon is running and hooks are configured. Events need to flow before memories can be created.

Permission denied

Symptom: npm install fails with "EACCES" or "permission denied" errors.

Likely cause: npm does not have permission to install global packages in the default location.

Fix:

On macOS/Linux, use the --global flag with proper permissions:
```
sudo npm install -g @sodasoft/nordon-cli
```

Or configure npm to use a different directory for global packages:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add ~/.npm-global/bin to your PATH

On Windows, run your terminal as Administrator or use nvm to manage Node installations.

Port already in use

Symptom: The daemon fails to start with "address already in use" or "EADDRINUSE".

Likely cause: Another process is using port 7533, or a previous daemon instance did not shut down cleanly.

Fix:

Change the port in your config file:

# ~/.config/nordon/config.toml
api_port = 9000

Start the daemon on the new port:
```
nordond --port 9000 &
```

Update the CLI to use the new port:

export NORDON_API_URL=http://127.0.0.1:9000

License activation failed

Symptom: nordon plan activate fails with "invalid key" or "activation failed".

Likely cause: The license key may be incorrect, expired, or the daemon is not running.

Fix:

Double-check your license key. Copy it directly from the confirmation email to avoid typos.
Make sure the daemon is running:
```
nordon status
```
Try activating again:
```
nordon plan activate <your-license-key>
```
If it still fails, check your account status:
```
nordon account status
```

Can't connect to daemon

Symptom: CLI commands hang or return "connection timed out".

Likely cause: The daemon is not reachable. This could be a port mismatch or a firewall blocking the connection.

Fix:

Check that the daemon is running:
```
nordon status
```
Make sure the port matches. If you changed the port in the config, the CLI needs to know:
```
export NORDON_API_URL=http://127.0.0.1:7533
```
Check if a firewall is blocking localhost connections. NORDON only uses 127.0.0.1 (localhost) — it does not need internet access to function.

Restart the daemon:

# Stop any existing instances
nordon service uninstall
# Start fresh
nordond &

Claude Code hooks not working

Symptom: Events are not being captured during Claude Code sessions.

Likely cause: The hooks are not configured in the right file, or the JSON is malformed.

Fix:

Verify the settings file path:
- macOS / Linux: ~/.claude/settings.json
- Windows: %USERPROFILE%\.claude\settings.json

Open the file and check that the JSON is valid. A missing comma or bracket will break it. The hooks section should look like:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "command": "nordon hook post-tool \"$TOOL_NAME\"",
      "timeout": 5000
    }],
    "Stop": [{
      "matcher": "",
      "command": "nordon hook session-end",
      "timeout": 10000
    }]
  }
}

Make sure the daemon is running:
```
nordon status
```
Restart Claude Code to pick up the updated settings.
After a session, check if events are flowing:
```
nordon logs --limit 5
```

Still stuck?

Run diagnostics and check the output for clues:

nordon doctor
nordon logs --limit 50

If the issue persists, check out these resources:

Configuration·Guides·CLI Reference