--json output, and atlanai api Gateway calls. Run atlanai auth status with the CI token in the environment as the first diagnostic step.
Exit code 4 on a CI job that was working previously
The job exits with code 4 after previously completing successfully.
Cause
ATLANAI_TOKEN is missing from the environment or the token has been revoked. Exit code 4 always indicates an authentication failure.
Solution
Verify the token is present and valid in the CI environment.- Confirm the secret is set in your CI secret store and has not expired.
- Run
atlanai auth statuswith the token in the environment. - Verify the token resolves to the expected account.
- Rerun the job after confirming the token is valid.
--json exits with an error listing valid field names
The command fails and prints the names of the fields the format accepts.
Cause
The field names passed to--json do not match the record’s actual field names. The CLI reports each unknown field name and exits with a non-zero code.
Solution
Use the field names listed in the error output.- Read the error output to identify the valid field names for this command.
- Rerun the command with the correct field names passed to
--json.
atlanai api returns a 403 on a Gateway endpoint
A direct Gateway API call returns a 403 Forbidden response.
Cause
The authenticated account does not have access to that operation or workspace. Gateway operations enforce workspace-level and operation-level permissions independently.Solution
Confirm the account’s identity and permissions before retrying.- Run
atlanai auth statusto confirm the active identity. - Verify the workspace and operation are within the account’s permissions.
- Ask your workspace administrator to grant access if needed.
- Retry the call after the permission is updated.
See also
- Automate workflows: Use structured output, stable exit codes, API-key auth, and the Gateway API.
- Run diagnostics: Inspect installation, daemon logs, and authentication state.