Skip to main content

​
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 summaryCauseResolution
”Not logged in”No stored credentials foundRun nexudus login to authenticate
”Unauthorized”Invalid or expired credentialsRun nexudus login again with correct credentials
”Forbidden”Your account lacks API permissionsContact your Nexudus administrator to grant API access
”not found”The entity ID does not existDouble-check the ID — use list to find valid IDs
”Failed to create”Validation error on createCheck required fields — run nexudus <entity> create --help for details
Non-zero exit codeGeneral command failureRead 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.