Get Unstuck

On this page

• Quick triage command ladder
• Typical failures
• Task stuck or blocked
• Capture useful logs
• Validate config quickly

Quick triage command ladder (copy/paste)

cara version
cara status --port 18789
curl -sS http://127.0.0.1:18789/health
cara logs -n 80

Run top-to-bottom, then branch into the sections below based on first failure.

Typical failures

• 401 Unauthorized
  • Token mismatch between request and gateway.auth.token.
• Connection refused
  • Service not running, wrong host/port, or bind mode mismatch.
• agent model is not configured
  • Set agents.defaults.model to a colon-form provider:model value, or set agents.defaults.route to a route that resolves to one.
• requested route is not configured
  • Confirm the route name in agents.defaults.route or an agent override matches a key under top-level routes.
• model "..." uses slash syntax
  • Replace slash-form model values such as openai/gpt-5.5 with colon-form values such as openai:gpt-5.5.
• No provider is currently available
  • Provider key/config not active in the same shell/session, or hot reload rolled back to the last usable provider snapshot.
• Channel inbound not working
  • Missing channel token/secret or external platform webhook/intents not configured.

Task stuck or blocked

If long-running autonomy tasks are not progressing:

curl -sS -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" \
  "http://127.0.0.1:18789/control/tasks?state=blocked&limit=20"

Inspect a specific task:

curl -sS -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" \
  "http://127.0.0.1:18789/control/tasks/<task_id>"

Common operator actions:

• Resume blocked task:

  curl -sS -X POST -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" \
    -H "content-type: application/json" \
    -d '{"delayMs":1000,"reason":"operator resume"}' \
    "http://127.0.0.1:18789/control/tasks/<task_id>/resume"

• Retry failed/cancelled task:

  curl -sS -X POST -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" \
    -H "content-type: application/json" \
    -d '{"delayMs":500,"reason":"operator retry"}' \
    "http://127.0.0.1:18789/control/tasks/<task_id>/retry"

• Patch payload/policy before retry:

  curl -sS -X PATCH -H "Authorization: Bearer ${CARAPACE_GATEWAY_TOKEN}" \
    -H "content-type: application/json" \
    -d '{"policy":{"maxRunTimeoutSeconds":45},"reason":"operator patch"}' \
    "http://127.0.0.1:18789/control/tasks/<task_id>"

Capture useful logs

Run with debug logging:

RUST_LOG=debug CARAPACE_CONFIG_PATH=./carapace.json5 cara

If service is running already:

cara logs -n 200

cara logs prints the last N log lines (it does not stream continuously), so re-run it as needed while debugging.

Validate config quickly

• Compare your config against config.example.json5
• Confirm auth mode is intentional (token, password, or none for local-only)
• Confirm agents.defaults.model uses provider:model or agents.defaults.route names a configured route
• Confirm channel secrets are present for enabled channels

Ask for help or report problems

• Guided setup or team evaluation: Help
• Setup smoke feedback: https://github.com/puremachinery/carapace/issues/new?template=setup-smoke-report.yml
• Bug report: https://github.com/puremachinery/carapace/issues/new?template=bug-report.yml
• Feature request: https://github.com/puremachinery/carapace/issues/new?template=feature-request.yml

For security vulnerabilities, use private reporting: https://github.com/puremachinery/carapace/security/advisories/new