HSX_E_TOKEN_KEY_CUSTODY_UNAVAILABLE

01 · Meaning

What this error means

The custody mechanism could not store or read the key (e.g. the macOS `security` CLI failed), so the deploy stopped before mutating anything.

When this error stops a command, hs-x exits with code 1. With --json, the failure is reported as a structured error whose code field is HSX_E_TOKEN_KEY_CUSTODY_UNAVAILABLE — stable to match on in scripts and agents.

02 · Causes

Likely causes

• The macOS Keychain is locked or security was denied access
• HSX_TOKEN_KEY_CUSTODY=keychain on a machine without a usable Keychain (CI, Linux)

03 · Fix

How to fix it

• Unlock the login keychain, or grant access when macOS prompts
• Use the default encrypted-file custody instead: unset HSX_TOKEN_KEY_CUSTODY (or set HSX_TOKEN_KEY_CUSTODY=file)

Still stuck? Re-run the command with --debug for the wire-level detail, or hs-x doctor to check accounts, link state, and connectivity in one pass.