Control Zero error code reference

Every user-visible error from the Control Zero SDK and CLI carries a stable E#### code. Each code has its own page on this site; click the code in any error message and you land on the canonical fix.

The SDK codes are defined once in the shared error catalog (sdks/error-catalog/error_codes.yaml) and mean the same thing in the Python and Node SDKs.

The codes are organized by area:

Range	Area
E1000-E1099	Security and secrets management
E1100-E1199	Authentication and enrollment
E1200-E1299	Policy load / validate / bundle
E1300-E1399	Approvals (HITL) request / wait flow
E1400-E1499	Network and remote backend
E1500-E1599	Approval gate, hook subprocess, agent integration
E1600-E1699	SDK runtime (guard / audit / close)
E1700-E1799	HITL (Human-in-the-Loop) approvals and secrets
E2000-E2099	Credential leak detection
E3000-E3299	Platform backend (API / SSO)
E4000-E4099	Governance gateway

Security and secrets (E10xx)

• E1001 -- API key found in agent settings file
• E1002 -- ~/.controlzero directory is world-readable
• E1003 -- config.yaml is world-readable
• E1004 -- API key found in shell history
• E1005 -- Cannot read an agent settings file

Authentication and enrollment (E11xx)

• E1101 -- API key rejected (401)
• E1102 -- Enrollment token expired
• E1103 -- No API key found
• E1104 -- API key format invalid

Policy load / validate / bundle (E12xx)

• E1201 -- Policy file failed validation
• E1202 -- Policy file not found
• E1203 -- Policy bundle signature mismatch
• E1204 -- Policy version conflict
• E1205 -- Policy bundle missing, fail-closed engaged

Cache and local-disk layout (E13xx)

• E1301 -- Cache directory permissions wrong
• E1302 -- Stale bundle for rotated key
• E1303 -- Audit log not writable

Network and remote backend (E14xx)

• E1401 -- Backend unreachable
• E1402 -- Backend returned 5xx
• E1403 -- Rate limit exceeded
• E1404 -- TLS verification failed

Approval gate and hook subprocess (E15xx)

• E1500 -- Approvals disabled at this scope
• E1501 -- Hook input was not JSON
• E1502 -- Hook timed out
• E1503 -- Hook returned the wrong decision key
• E1504 -- Windows agent hook syntax error

SDK runtime (E16xx)

• E1601 -- guard() called after close()
• E1602 -- Tool name not in canonical vocab
• E1603 -- Args hash mismatch (deterministic check)

HITL approvals and secrets (E17xx)

The approval (human-in-the-loop) flow is in Beta and available on every deployment, including the hosted (SaaS) plan. Approvals are off by default; an administrator turns them on per scope. See Approval Workflow for availability and Set up approvals for the toggle.

• E1701 -- Approval request timed out
• E1702 -- Approval backend unreachable
• E1703 -- Approval policy version conflict
• E1704 -- Approvals not configured for this org
• E1705 -- No approver available
• E1706 -- Requestor identity not in org
• E1707 -- Requestor identity required
• E1708 -- Requestor identity claim rejected
• E1709 -- Secret value leak in payload
• E1710 -- Secret approval required
• E1711 -- Secret not found
• E1712 -- Bundle requires a newer SDK

Credential leak detection (E20xx)

• E2001 -- Credential leak detected in tool output

Platform backend (E3xxx)

Returned by the Control Zero platform API in the structured error body { "error": { "code", "reason_code", "request_id", ... } }. The reason_code is the stable E####; quote the request_id to support so the error can be traced to its logs.

Code	Meaning
E3000	Internal server error
E3001	Request failed validation
E3002	Resource not found
E3003	Permission denied
E3004	Authentication required or failed
E3005	Rate or usage limit exceeded
E3006	An upstream dependency is unavailable
E3007	State conflict / already exists
E3008	Integrity / cross-tenant violation
E3009	Service unavailable
E3010	Malformed request
E3011	CSRF token missing or invalid
E3012	Request body exceeds the size cap
E3200	SSO not configured for this organization
E3201	SSO is configured but invalid
E3202	Identity provider unreachable
E3203	SSO state missing, expired, or tampered
E3204	SSO token / assertion rejected
E3205	No role mapping, or tier disallows the role
E3206	Account is suspended or inactive

Governance gateway (E4xxx)

Returned by the governance gateway. Enforcement-path failures fail closed: if the gateway cannot complete its policy / DLP / auth checks it denies the request rather than forwarding it.

Code	Meaning
E4000	Internal gateway error (non-enforcement path)
E4001	Governance evaluation failed; request denied (fail-closed)
E4002	Malformed request
E4003	Rate limit exceeded
E4004	Authentication required or invalid
E4005	Governance gateway is not initialized

Reporting a new error you've hit

If controlzero doctor reports a code you can't find a page for, the page hasn't been published yet. Open an issue at github.com/controlzero/control_zero/issues and include the full error message and your controlzero env-dump output (with --show-secrets left OFF).