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

{
  "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:

# Check exit code
nexudus products get 12345678 --json
if [ $? -ne 0 ]; then
  echo "Command failed"
fi

# 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:

nexudus doctor

This checks:

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