Troubleshooting

Start with the health check:

nbx doctor --verbose

Command not found

Restart your shell, then check:

command -v nbx
nbx version

If nbx is still unavailable, run the installer again.

Box not found

Run nbx list and confirm you are inside the intended project. Analyze the project if it has no box:

nbx analyze .

Analysis is stale

nbx status --check
nbx analyze .

Use nbx analyze --force only when normal analysis does not repair the mismatch.

Search is empty or irrelevant

Confirm the selected box, make the query more concrete, and choose an intent when useful:

nbx search "expired session retry" --intent debug

Inspect source before treating an empty result as proof of absence.

Definition is ambiguous

Several symbols may share a name. Add a file path or use the UID returned by nbx def:

nbx def validate --file src/auth/validator.ts

Agent integration is missing or outdated

nbx configure --force
nbx configure status

Restart the coding client after configuration.

A graph query fails

Inspect the current schema, bind every relationship variable you return, and add a limit:

nbx schema

Before resetting

nbx reset --force removes Noodlbox-managed state. It is not a general first repair step. Use automatic fixes offered by nbx doctor --fix first.

Report a problem

Run nbx feedback and include the installed version, failing command, redacted output, target box, and reproduction steps.