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 67 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_NO_HSX_ACCOUNT`	No HS-X account exists	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 human-gated	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_LINK_NOT_MEMBER`	Not a member of the target account	1
`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_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_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.