| title | Error Codes |
|---|
Structured JSON failures include error.code when the CLI can classify the recovery path. Agents and scripts should branch on error.code first, then error.message.
This catalog is the source of truth for stable codes. CI runs make snapshot-error-codes to assert that every Code: literal in internal/cli/*.go is documented here (or matches a documented dynamic prefix).
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
AUTH_UNAUTHENTICATED |
3 | No usable local session exists. | Run agora login. |
AUTH_SESSION_EXPIRED |
3 | The stored session is expired or rejected after refresh. | Run agora login again. |
AUTH_OAUTH_EXCHANGE_FAILED |
1 | The OAuth token endpoint rejected the authorization-code or refresh-token exchange. | Retry login; if persistent, file a bug with the HTTP status and request ID. |
AUTH_OAUTH_RESPONSE_INVALID |
1 | The OAuth token endpoint returned a response missing required token fields. | Retry login; if persistent, file a bug. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
PROJECT_NOT_SELECTED |
1 | No explicit, repo-local, or global project context is available. | Pass --project, work inside a bound quickstart, or run agora project use <project>. |
PROJECT_NOT_FOUND |
1 | The requested project ID or exact name was not found. | Run agora project list and retry with the project ID. |
PROJECT_AMBIGUOUS |
1 | A project name matched multiple projects. | Retry with the project ID. |
PROJECT_NO_CERTIFICATE |
1 | The selected project has no app certificate for env seeding. | Enable an app certificate in Console or select another project. |
PROJECT_ENV_TEMPLATE_UNKNOWN |
1 | The --template value for project env write is not supported. |
Use nextjs or standard. |
PROJECT_NOT_READY |
1 | project doctor could not surface a more specific issue. |
Re-run project doctor for details. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
QUICKSTART_TEMPLATE_REQUIRED |
1 | init needs a template in JSON, CI, or non-TTY mode. |
Pass --template or run agora quickstart list. |
QUICKSTART_TEMPLATE_UNKNOWN |
1 | The template ID is not known to this CLI. | Run agora quickstart list. |
QUICKSTART_TEMPLATE_UNAVAILABLE |
1 | The template exists but is not currently available. | Choose an available template. |
QUICKSTART_TEMPLATE_ENV_UNSUPPORTED |
1 | The selected template does not define an env target path. | Choose a template with env support or configure the env file manually. |
QUICKSTART_TARGET_EXISTS |
1 | The clone target already exists. | Choose a new directory. |
INIT_NAME_REQUIRED |
1 | agora init was run without the required target directory name. |
Pass a directory name, for example agora init my-nextjs-demo --template nextjs. |
INIT_ABORTED |
1 | The interactive agora init reuse prompt was answered "no". |
Re-run with --project <id>, --new-project, or accept the prompt. |
PROJECT_NAME_REQUIRED |
1 | agora project create (or the equivalent MCP tool) was called without name. |
Pass a project name, for example agora project create my-app. |
These codes only appear from the agora upgrade self-update path on installer-managed installs. Homebrew, npm, and other managed channels do not emit upgrade error codes — they always return status: "manual" with a manager-specific command.
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
UPGRADE_NETWORK_FAILED |
1 | Could not query the GitHub API for the latest release. | Check connectivity; provide GITHUB_TOKEN if rate-limited. |
UPGRADE_DOWNLOAD_FAILED |
1 | Could not download the release archive or checksums.txt. |
Check connectivity; retry; pin a specific version in the release page if needed. |
UPGRADE_CHECKSUM_FAILED |
1 | The downloaded archive failed SHA-256 verification. | Do not continue; retry the download; inspect for a transparent proxy rewriting downloads. |
UPGRADE_EXTRACT_FAILED |
1 | The new binary could not be extracted from the archive. | File a bug with the archive contents. |
UPGRADE_BINARY_RESOLVE_FAILED |
1 | The CLI could not locate its own running executable. | Re-run with the absolute path to agora. |
UPGRADE_INSTALL_FAILED |
1 | The new binary could not replace the running one (typically a Windows file-in-use error or a non-writable install dir). | Close other agora processes, or run from an elevated shell, then retry. |
UPGRADE_UNSUPPORTED_PLATFORM |
1 | Self-update does not support the current OS/arch combination. | Use the platform installer manually. |
These codes appear inside data.checks[].issues[].code and (for blocking issues) propagate to the top-level error.code when JSON-mode project doctor exits non-zero.
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
WORKSPACE_SCAN_FAILED |
1 | project doctor --deep could not enumerate the repo workspace. |
Inspect the directory permissions and retry. |
LOCAL_PROJECT_BINDING_INVALID |
1 | .agora/project.json exists but is missing projectId. |
Re-bind the repo: agora project use <project> or agora init from the repo root. |
LOCAL_PROJECT_BINDING_MISMATCH |
1 | .agora/project.json points at a project that does not match the selected project. |
Use --project to select the bound project, or rebind. |
WORKSPACE_TEMPLATE_UNKNOWN |
1 | The CLI could not detect the quickstart template for this repo. | Pass --template to the failing command. |
WORKSPACE_ENV_PATH_UNKNOWN |
1 | The CLI could not determine the quickstart env target path. | Pass --template and re-run; if persistent, file an issue. |
WORKSPACE_ENV_FILE_MISSING |
1 | A quickstart env file expected by the bound template is missing. | Run the command from suggestedCommand (typically agora quickstart env write). |
WORKSPACE_ENV_READ_FAILED |
1 | The CLI could not read the quickstart env file. | Run the command from suggestedCommand (agora quickstart env write . --project <id> --overwrite); if it still fails, inspect file permissions and contents. |
WORKSPACE_ENV_PROJECT_MISMATCH |
1 | The quickstart env file points at a different App ID than the selected project. | Run the command from suggestedCommand to overwrite the env file. |
WORKSPACE_ENV_METADATA_MISSING |
1 | The quickstart env file is missing Agora-managed project metadata comments. | Run the command from suggestedCommand to refresh metadata. |
WORKSPACE_ENV_APP_ID_MISSING |
1 | A quickstart env file is missing the required app ID key. | Run the command from suggestedCommand. |
WORKSPACE_ENV_APP_ID_MISMATCH |
1 | A quickstart env file points at a different app ID. | Run the command from suggestedCommand. |
APP_CREDENTIALS_MISSING |
1 | The selected project has no app ID / app certificate yet. | Run the command from suggestedCommand (agora project show --project <id>) to re-fetch credentials; if still missing, enable the app certificate in Console (agora open --target console). |
TOKEN_CAPABILITY_DISABLED |
(warning) | The project has token issuance disabled. | Enable token issuance in Console. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
SKILL_NOT_FOUND |
1 | agora skills show <id> was given an unknown skill ID. |
Run agora skills list to see available IDs. |
Some doctor codes are generated from the feature name at runtime. Agents should match by prefix.
| Pattern | Example | Meaning | Recovery |
|---|---|---|---|
FEATURE_<NAME>_PROVISIONING |
FEATURE_RTC_PROVISIONING |
The named feature is being provisioned (warning). | Wait and re-run project doctor. |
FEATURE_<NAME>_DISABLED |
FEATURE_CONVOAI_DISABLED |
The named feature is disabled for this project. | Run the command from suggestedCommand or enable the feature in Console. |
INSTALL_DOCTOR_<STATUS> |
INSTALL_DOCTOR_NOT_READY |
agora doctor (top-level) summary code, where <STATUS> is WARNING, NOT_READY, or AUTH_ERROR. The detailed per-check items live in data.blockingIssues[].code / data.warnings[].code and follow the same dotted naming as project doctor codes (e.g. INSTALL_PATH_RESOLUTION, NETWORK_API_DNS). |
Read data.summary and the per-check suggestedCommand. |
<NAME> is uppercased and matches the feature ID set returned by agora introspect --json under data.enums.features (currently RTC, RTM, CONVOAI).
Failures returned by the Agora API preserve the upstream code, httpStatus, and requestId in the envelope when present. Agents should treat any error.code not in this catalog and not matching a dynamic prefix as a passthrough from the API and log/escalate it rather than handling it.
Common API error codes are not enumerated here because they may evolve independently of the CLI; consult the API documentation when handling them programmatically.