Documentation

Troubleshooting

Diagnose verify failures, CLI and install doctor output, auth errors, and webhook delivery problems — with the same reason strings and error codes the product returns.

Quick diagnosis

Symptom	First command	What to look for
CLI or MCP feels broken	`behalf doctor`	Any `error` / `warn` rows and their `fix:` lines
verify always denied	`behalf --json verify …` or Logs	Exact `reason` string (see table below)
401 / auth failures	`behalf whoami` + `behalf config list`	API key format `bhf_sk_…`, agent id, base URL
Webhooks not arriving	Dashboard → Webhooks detail	`lastError`, dead-letter flag, attempt count
Managed Profiles bypass	`behalf profile doctor`	PATH order, shim vs real binary, required-mode prerequisites
Install / MCP registration	`npx @behalfid/install doctor --json`	`healthy`, `errors[].code`, `remediation`

CLI doctor

behalf doctor checks config directory, session, agent id, API key shape, base URL, API health, project .mcp.json, context file, and supported action-time hooks (Claude PreToolUse, Codex PreToolUse, Cursor beforeShellExecution).

terminal

behalf doctor
behalf --json doctor

Common fixes the doctor suggests:

Not logged in — behalf login for dashboard-scoped commands (permissions, some logs). Agent API keys alone are enough for verify.
API key / agent id missing — behalf config set api-key bhf_sk_… and behalf config set agent-id agent_…. Keys are shown once at agent creation.
API health error — check behalf config get base-url (default https://behalfid.com) and network.
Missing MCP / hook — behalf mcp init, then behalf claude / behalf codex / behalf cursor.
Cursor CLI not in PATH — in Cursor, run “Install cursor command in PATH”, then re-run behalf cursor.

Diagnosing verify failures

A verify response always includes allowed, reason, risk, and requestId. Prefer the exact reason over guessing. Fail closed: if allowed is false, or verify is unavailable, do not run the tool.

terminal

behalf --json verify agent_xxx --action deploy --vendor vercel.com
behalf logs agent_xxx --denied

Common decision reasons

Reason	Meaning	Fix
`No active permission exists for this action.`	No matching active permission for the agent/action	Create a permission for that action (and vendor/resource if scoped)
`Permission requires approval before execution.`	Permission has `requiresApproval`; not yet granted	Approve in Approvals / Inbox, then retry with the same context
`Agent is disabled.`	Agent record disabled	Re-enable the agent in the dashboard
`Permission has been revoked.` / `Permission has expired.`	Permission no longer active	Create a new permission or extend expiry
`Action is blocked by this permission.`	Matched `blockedActions`	Remove the block or use a different action string
`Action is not included in allowedActions.`	Permission narrowed to an allow-list that excludes this action	Add the action to `allowedActions` or verify the exact string
`Resource does not match permission resource.`	Vendor/resource mismatch	Pass the same resource/vendor the permission was created with
`Amount exceeds maxAmount constraint.`	Amount above limit	Lower the amount or raise `maxAmount`
`amount is required for permissions with a maxAmount constraint.`	Constraint present but amount omitted	Pass `amount` on verify
`Vendor is not included in allowedVendors constraint.`	Vendor allow-list miss	Use an allowed vendor or update the constraint
`Branch is blocked by deniedBranches constraint.` / not in allowedBranches	Git branch context failed	Pass correct `branch` auth context or adjust constraints
`Environment is blocked by deniedEnvironments…`	Environment context failed	Pass `environment` (e.g. staging vs production) correctly
`path_not_permitted` / `command_blocked`	File path or execute_command blocked by constraints	Adjust `allowedPaths` / `deniedPaths` / `deniedCommands`
`Verification failed closed during permission lookup.`	Internal lookup failure — fail closed	Retry; check API health and logs. Do not execute.

Auth and API key issues

API / CLI message	Cause	Fix
`Missing or invalid API key.`	No Bearer token, wrong scheme, or key not starting with `bhf_sk_`	Send `Authorization: Bearer bhf_sk_…`; regenerate key if lost
`Unknown agent.`	agentId does not exist	Confirm id from dashboard / `behalf agents list`
`API key does not match this agent.`	Key belongs to a different agent or was rotated	Use the current key for that agent; rotate creates a new one-time secret
Permission create rejected	Agent API keys cannot grant permissions	Run `behalf login` or pass `--developer-token` (`bhf_dev_…`)
`Invalid email or password.`	Bad credentials or Google-only account	Use Google sign-in when the account is Google-linked

terminal

behalf whoami
behalf config list
behalf login

Webhook delivery failures

Events land in an outbox before the API returns. Delivery is asynchronous via /api/webhooks/process. A down receiver does not block verify().

Signature verification fails (401 on your side) — verify against the raw body; do not re-serialize JSON. Check BehalfID-Timestamp skew (default 300s) and the current whsec_… secret. Rotating the secret invalidates the previous one immediately.
Redirects — delivery does not follow redirects. Error: Endpoint returned a redirect, which is not followed for webhook delivery.
Timeouts / 5xx — retries use bounded exponential backoff (immediate → 5s → 30s → 2m → 10m). After five failures the event is dead-lettered.
Dead letter — fix the receiver, then replay from the webhook detail page (resets attempts and clears lastError). Pending/processing/completed events cannot be replayed.
Localhost — http://localhost only in development; production endpoints require https://.
Plan / quota — webhook delivery may require Pro. Check billing if endpoints never leave pending.

Full payload and signature details: Webhooks.

Installer errors (@behalfid/install)

Prefer JSON output. Codes match the installer's stable InstallerErrorCode set:

terminal

npx @behalfid/install doctor --json
npx @behalfid/install status --json
npx @behalfid/install install --force --json

Code	Typical cause	Action
`DETECTION_FAILED`	No usable AI clients found	Install/launch a supported client; pass `--clients`
`CONFIG_INVALID` / `CONFIG_READ_FAILED`	Broken MCP JSON/TOML	Fix syntax at the reported path; installer will not overwrite unreadable files
`CONFIG_WRITE_FAILED`	Permissions or file lock	Close locking apps; fix permissions; retry
`RUNTIME_REGISTRATION_FAILED`	MCP register step failed	Read nested error; re-run with `--force` after fix
`NOT_INSTALLED`	Operation requires prior install	`npx @behalfid/install install --json`
`VERIFY_FAILED`	Verify endpoint probe failed	Override with `--verify-endpoint https://your-host/api/verify`
`STATE_INVALID` / state errors	Corrupt `~/.behalfid/install-state.json`	Repair or remove state, then reinstall

Operator-depth guide (scenarios, warnings, platform notes): packages/install/docs/TROUBLESHOOTING.md in the repo — keep that file as the install-package source of truth; this page surfaces the same codes for product docs.

Managed Profiles

Run behalf profile doctor first. Frequent issues: ~/.behalf/bin not first on PATH, missing real tool binaries, unauthenticated CLI, required-mode prerequisites, and server-down cache behavior. Full checklist: CLI → Troubleshooting first-run failures.

Still stuck?

Capture behalf --json doctor (redact secrets if sharing).
Note the verify requestId and reason from Logs.
For webhooks, copy eventId, attempt count, and sanitized lastError.
Confirm fail-closed behavior in your executor — denied and unavailable must not execute.

Related: CLI, SDK, Concepts, Security.