Reference · Error codes

CLI error codes.

When a command fails, hs-x prints a stable HSX_E_* code and a link into this reference. Every code below is generated from the same registry the CLI ships, so the page for a code always matches the binary that printed it. Each one covers what the error means, the likely causes, and how to fix it; --json output carries the same code and a docs_url field.

Outcome: You can resolve any HSX_E_* code the CLI prints — or hand the page to your coding agent and let it do the fixing.

All 85 codes

In registry order, which groups codes by family: input parsing, scaffolding, migration, deploy, local dev, accounts and sessions, API calls, credential exchanges, and linking. The exit column is the process exit code hs-x terminates with when the error stops a command.

Code	What happened	Exit
`HSX_E_INPUT_UNKNOWN_COMMAND`	Unknown command	10
`HSX_E_INPUT_UNKNOWN_SUBCOMMAND`	Unknown subcommand	10
`HSX_E_INPUT_UNKNOWN_FLAG`	Unknown flag	10
`HSX_E_INPUT_MISSING_VALUE`	Flag missing value	10
`HSX_E_INPUT_MISSING_PATH`	Missing API path	10
`HSX_E_INPUT_MISSING_ACCOUNT_ID`	Missing account id	10
`HSX_E_INPUT_MISSING_PROJECT_ID`	Missing project id	10
`HSX_E_INPUT_INVALID_DEPLOY_PLAN`	Invalid deploy plan input	10
`HSX_E_INPUT_MISSING_PAK`	Missing HubSpot PAK	10
`HSX_E_INPUT_MISSING_CONNECT_FLAGS`	Missing connect flags	10
`HSX_E_INPUT_MISSING_API_TOKEN`	Missing Cloudflare API token	10
`HSX_E_INPUT_BAD_FIELD`	Cannot parse field	10
`HSX_E_INPUT_BAD_JSON`	Typed field is not valid JSON	10
`HSX_E_INPUT_BAD_NAME`	Invalid project name	10
`HSX_E_INIT_DIR_NOT_EMPTY`	Project directory already exists	10
`HSX_E_MIGRATE_NOTHING_PORTABLE`	Nothing portable to migrate	1
`HSX_E_CUTOVER_EXECUTE_GATED`	Cutover execution is gated	1
`HSX_E_CUTOVER_CONFIRM_REQUIRED`	Cutover needs an interactive confirmation	1
`HSX_E_CUTOVER_CONFIRM_MISMATCH`	Cutover confirmation did not match	1
`HSX_E_DEPLOY_SCHEMA_SCOPES`	HubSpot token is missing a property-write scope	10
`HSX_E_DEPLOY_SCHEMA_APPLY`	Portal schema apply failed	1
`HSX_E_DEPLOY_HUBSPOT_BUILD_COMPONENT`	HubSpot build component failed	1
`HSX_E_ROLLBACK_FAILED`	Rollback did not change live traffic	1
`HSX_E_ROLLBACK_CLOUDFLARE_CREDENTIALS`	Rollback needs a Cloudflare API token	1
`HSX_E_TOKEN_KEY_CUSTODY_MISSING`	Escrowed HSX_TOKEN_KEY not found in local custody	1
`HSX_E_TOKEN_KEY_CUSTODY_CORRUPT`	Token-key custody is unreadable or holds the wrong key	1
`HSX_E_TOKEN_KEY_CUSTODY_UNAVAILABLE`	Token-key custody mechanism unavailable	1
`HSX_E_LINK_NOT_MEMBER`	Not a member of the target account	1
`HSX_E_LINK_PREFLIGHT_NAMESPACE`	Link preflight: INSTALL_KV namespace missing or mismatched	10
`HSX_E_LINK_PREFLIGHT_STATE_CORRUPT`	Link preflight: tenant install state is corrupt	10
`HSX_E_LINK_PREFLIGHT_AMBIGUOUS`	Link preflight: install bindings are ambiguous	10
`HSX_E_LINK_PREFLIGHT_UNPROVEN`	Link preflight: token-key continuity cannot be proven	10
`HSX_E_LINK_PROBE_FAILED`	Link migration: token-resolution probe failed — rolled back	10
`HSX_E_LINK_MIGRATION_INTERRUPTED`	Link migration was interrupted — resume by re-running	70
`HSX_E_CUTOVER_EXECUTE_FAILED`	Cutover execution failed — rolled back	1
`HSX_E_DEV_NO_WORKERS`	No worker modules found	1
`HSX_E_DEV_UNKNOWN_CAPABILITY`	Unknown capability id	1
`HSX_E_DEV_NO_LAST_INVOCATION`	Nothing to replay	1
`HSX_E_DEV_WORKER_LOAD_FAILED`	Worker module failed to load	1
`HSX_E_DEV_BAD_ONLY`	Invalid --only selector	2
`HSX_E_DEV_PORT_IN_USE`	Dev server port already in use	1
`HSX_E_ACCOUNT_NOT_FOUND`	HS-X account not found	10
`HSX_E_API_NO_CONTROL_PLANE`	No HS-X control plane configured	10
`HSX_E_API_NO_HUBSPOT_AUTH`	No HubSpot API credential	10
`HSX_E_API_UNAUTHORIZED`	API rejected your credentials	10
`HSX_E_API_NOT_FOUND`	API resource not found	50
`HSX_E_API_CONFLICT`	API conflict	50
`HSX_E_API_RATE_LIMITED`	Rate limited	50
`HSX_E_API_BAD_REQUEST`	Bad request to the API	50
`HSX_E_API_SERVER`	Upstream server error	51
`HSX_E_API_NETWORK`	Network error	40
`HSX_E_API_UNEXPECTED`	Unexpected API response	50
`HSX_E_NOT_LOGGED_IN`	No HS-X session on this machine	10
`HSX_E_SESSION_EXPIRED`	HS-X session expired	10
`HSX_E_HUBSPOT_PAK_INVALID`	HubSpot PAK rejected	10
`HSX_E_HUBSPOT_PAK_EXCHANGE`	HubSpot PAK exchange failed	10
`HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT`	HubSpot account not in CLI config	10
`HSX_E_DEV_SESSION_NO_NODES`	No matching nodes in project IR	10
`HSX_E_DEV_SESSION_REGISTER`	Dev session register failed	50
`HSX_E_CLOUDFLARED_MISSING`	cloudflared binary missing	50
`HSX_E_CLOUDFLARED_SPAWN`	cloudflared spawn failed	50
`HSX_E_CLOUDFLARED_EXITED`	cloudflared exited before reporting a tunnel URL	50
`HSX_E_CLOUDFLARED_TIMEOUT`	cloudflared did not report a tunnel URL in time	50
`HSX_E_CLOUDFLARE_OAUTH_NOT_CONFIGURED`	Cloudflare OAuth not configured	10
`HSX_E_CLOUDFLARE_OAUTH_LISTENER`	OAuth callback listener failed	10
`HSX_E_CLOUDFLARE_OAUTH_TIMEOUT`	OAuth callback timed out	10
`HSX_E_CLOUDFLARE_OAUTH_AUTHORIZE`	Cloudflare denied authorization	10
`HSX_E_CLOUDFLARE_OAUTH_STATE_MISMATCH`	OAuth state mismatch	10
`HSX_E_CLOUDFLARE_OAUTH_EXCHANGE`	OAuth token exchange failed	10
`HSX_E_CLOUDFLARE_OAUTH_REFRESH`	OAuth refresh failed	10
`HSX_E_CLOUDFLARE_TOKEN_INVALID`	Cloudflare token rejected	10
`HSX_E_CLOUDFLARE_TOKEN_VERIFY`	Cloudflare token verify failed	10
`HSX_E_CLOUDFLARE_AUTH_FAILED`	Cloudflare rejected the API credential	10
`HSX_E_CLOUDFLARE_SCRIPT_NOT_FOUND`	Worker script not found on Cloudflare	40
`HSX_E_CLOUDFLARE_VERSION_NOT_FOUND`	Worker version not found or not deployable	40
`HSX_E_CLOUDFLARE_DEPLOYMENT_AMBIGUOUS`	Cloudflare deployment result is ambiguous	50
`HSX_E_CLOUDFLARE_VERSIONS_API`	Cloudflare Worker Versions API request failed	50
`HSX_E_CLOUDFLARE_TOKEN_PERMISSIONS`	Cloudflare token is missing required permissions	10
`HSX_E_LINK_REQUIRED`	Command requires a linked HS-X account	10
`HSX_E_LINK_NO_POINTER`	Project has no Cloudflare pointer yet	10
`HSX_E_LINK_NOT_CLAIMABLE`	Project owner is already attached to a different HS-X account	10
`HSX_E_UPDATE_INSTALL_FAILED`	Self-update install failed	1
`HSX_E_INTERNAL`	Internal error	1
`HSX_E_INPUT_INVALID`	Invalid input	10
`HSX_E_LOGS_UNAVAILABLE`	Logs unavailable	1

Codes are stable identifiers: scripts and agents can match on them (hs-x <command> --json reports failures as { "code": "HSX_E_…", "docs_url": "…" }). New codes appear here with the release that introduces them. See the CLI reference for the commands themselves.