# 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](operations.md)
- **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](operations.md#scaling-and-resource-budgets) · [Package admission](packages.md)
- **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](integrations.md)
- **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](reference.md)

## 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](https://github.com/chromium/chromium/blob/main/net/cert/internal/trust_store_mac.cc) · [Configure the managed listener](operations.md)