FAQ and Troubleshooting

FAQ and Troubleshooting

Jobs fail with 401 Unauthorized / invalid x-api-key

The model key Coop loaded is wrong or empty.

• Local vault: re-seal a valid sk-ant-… key: COOP_SECRET_VALUE='sk-ant-...' coop vault put ~/.coop/vault.json byok-anthropic, and confirm the manifest's provider_id matches the secret name.
• Azure Key Vault: confirm the service principal has the Get secret permission and that AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET (or AZURE_KEYVAULT_TOKEN) are exported for the daemon process. See BYOK Secrets.

vault is locked; POST /api/v1/vault/unlock

The daemon started without an unlocked vault. Either start with COOP_VAULT=… COOP_PASSPHRASE=… coopd serve, or unlock at runtime:

curl -X POST http://127.0.0.1:9700/api/v1/vault/unlock \
  -H 'content-type: application/json' \
  -d '{"path":"~/.coop/vault.json","passphrase":"…"}'

(Azure-KV-backed hens don't need the local vault unlocked.)

A hen refuses to hatch with a network-policy error

This is fail-closed behavior, not a bug. A policy stricter than open can't be enforced on this host (no Linux user namespaces, no macOS Seatbelt, or COOP_SANDBOX=0), or the hen uses a tmux CLI agent (agent_kind != anthropic) which isn't sandboxed in v1. Options: run on a host with the sandbox available, use agent_kind: anthropic, or set the policy to open. See Network Isolation.

403 Forbidden when accessing the UI/API from another machine

The loopback Host/Origin allowlist rejects non-loopback requests until you opt in. Set COOP_PUBLIC=1 and keep COOP_API_TOKEN set. Behind a proxy, also ensure the proxy and coopd share a Docker network. See Deployment.

502 Bad Gateway behind a reverse proxy / tunnel

The proxy can't reach the daemon. Put them on the same Docker network: docker network connect <proxy-net> coopd. A missing DNS record shows as NXDOMAIN, not a coopd error. See Deployment.

bash commands can't reach the network

Expected under network.policy: off or allowlist — bash gets no direct egress in v1. Allow-listed egress is delivered through the http tool instead. See Network Isolation.

HTTP 413 on a job/task submission

The prompt exceeds COOP_MAX_PROMPT_BYTES (default 256 KiB). Raise it, or set it to 0 to disable the cap.

HTTP 429 on login

The login throttle tripped (COOP_LOGIN_MAX_ATTEMPTS failures within 60s from your IP). Wait for the Retry-After window; a successful login clears it.

Where do I report a security issue?

Privately — see Security Model. Do not open a public issue.