Daedro / Handbook
Chapters
HandbookChapterRead Markdown ↗

Troubleshoot a call

Start with the URL, the requested operation and the response status. The Hub, an individual instance and an external adapter each enforce their own access and setup requirements.

A connection fails

  • TLS verification failed. Use the loopback HTTPS address and the CA from this installation. For curl, pass --cacert with the operator-issued ca.crt. Prepare the workspace
  • HTTP 401 or 403. Check that the credential belongs to this installation and has the right role. Starting, stopping or inspecting the operator-managed cleaning pool requires administrator access.
  • HTTP 404 for an instance. Confirm the ID with an authenticated list of visible instances. Private instances are available only to their creator and an administrator.

A deployment or call is rejected

  • HTTP 409. For deployment_stopped, have the operator start the pool. For deployment_busy, allow outstanding calls to finish before retrying the stop.
  • HTTP 429. Retry capacity_exceeded when a slot is free. If an upload was rejected, check its per-owner and installation size and count limits. Resource budgets · Package admission
  • HTTP 503. For deployment_unavailable, check the selected local Docker socket, pinned image and Docker health. Restore the original journal and keys if startup reports an integrity failure. Keep existing state available for operator inspection.

A catalog or adapter looks wrong

  • Unknown service. Read the exact ID from GET /api/v1/services. HTTP returns 404 with {"error":"service_not_found"} for an unknown ID. MCP returns a tool error.
  • HTTP 401 or 404 on an external component. Use that component's address and bearer token, and enable its api_mcp profile for application REST calls where the service requires it. Integration catalog
  • Index or provider unavailable. Follow the selected service card's setup instructions. Search needs a prepared index. External model calls require authorization to send the data and an available provider.
  • No search results. Use Clear filters to reset the query, category and protocol. Select Profile details or Connection guide on the resulting listing.

Check the server's active contract when a route or tool differs from an example. Live reference

The workspace opens, but the protected connection fails

Open /workspace or /upload on the catalog to prepare a profile or check a file locally. On macOS the system can verify a certificate using a hostname-specific trust setting that Chromium skips. The embedded browser can therefore display a certificate warning even when the system check succeeds. Use Use a verified terminal command inside the local page and point --cacert at the installer's verified public CA certificate. For a public service, issue a publicly trusted certificate for the exact DNS name. Chromium's macOS certificate verifier · Configure the managed listener