> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Common errors returned by the Nexudus CLI and how to resolve them.

# Error Handling

When a command fails, the CLI returns a non-zero exit code. If you're using `--json` or `--agent` output mode, the envelope's `ok` field is `false` and the `summary` field contains the error message.

## Error envelope

```json theme={null}
{
  "ok": false,
  "data": null,
  "summary": "Not logged in. Run 'nexudus login' first.",
  "breadcrumbs": ["businesses", "list"]
}
```

## Common errors

| Error summary      | Cause                              | Resolution                                                               |
| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ |
| "Not logged in"    | No stored credentials found        | Run `nexudus login` to authenticate                                      |
| "Unauthorized"     | Invalid or expired credentials     | Run `nexudus login` again with correct credentials                       |
| "Forbidden"        | Your account lacks API permissions | Contact your Nexudus administrator to grant API access                   |
| "not found"        | The entity ID does not exist       | Double-check the ID — use `list` to find valid IDs                       |
| "Failed to create" | Validation error on create         | Check required fields — run `nexudus <entity> create --help` for details |
| Non-zero exit code | General command failure            | Read `stderr` or the JSON envelope for details                           |

## Checking for errors in scripts

When scripting, always check the exit code or parse the envelope:

```bash theme={null}
# Check exit code
nexudus products get 12345678 --json
if [ $? -ne 0 ]; then
  echo "Command failed"
fi
```

```bash theme={null}
# Parse the envelope with jq
result=$(nexudus products list --json)
ok=$(echo "$result" | jq -r '.ok')
if [ "$ok" != "true" ]; then
  echo "Error: $(echo "$result" | jq -r '.summary')"
fi
```

## Diagnostics

If you're unsure why commands are failing, run diagnostics:

```bash theme={null}
nexudus doctor
```

This checks:

* Whether credentials are stored and valid.
* Whether the API is reachable.
* Whether the CLI is up to date.