Skip to content

Troubleshooting and support

These checks apply to Canvus MCP 26.11.0. Replace the example hostname and run from /opt/canvus-mcp on your own host, using sudo for Docker if required by your installation. No diagnostic-bundle generator is claimed to exist.

First checks

Record the time/timezone and exact error, then check service status:

docker compose -f compose.yaml ps --all canvus-mcp

Check liveness and readiness over the canonical HTTPS name from the execution host; keep certificate verification enabled:

curl --silent --show-error --write-out '\nHTTP %{http_code}\n' https://mcp.customer.example/healthz
curl --silent --show-error --write-out '\nHTTP %{http_code}\n' https://mcp.customer.example/readyz

healthz reports process liveness. readyz reports local storage/manual/maintenance readiness, not backend compatibility, AI-provider permissions or cloud reachability. A local curl result cannot establish access from Anthropic's cloud. The container has no curl or shell; use your host tools.

Service does not start or storage fails

Read a short local log window; inspect it before sharing anything:

docker compose -f compose.yaml logs --no-color --tail 100 canvus-mcp
  • state directory ... must be a real directory with mode 0700: check that the mounted host state/ exists, is a directory and has the expected permissions/UID mapping. Do not make it world-writable.
  • key_file must be a regular private file (0600/0400), exactly 32 raw bytes: verify the file metadata locally, not its contents. Restore only a matching known-good key; never overwrite it with a fresh key against existing state.
  • storage_unavailable: check capacity and ownership on the filesystem holding /opt/canvus-mcp/state. Use your host's disk-usage tools and inspect the mount, not a newly created empty directory. Stop for supported recovery if storage is damaged; do not delete state.db, WAL files or receipts.
  • maintenance_or_shutdown: determine whether a planned stop is underway; otherwise inspect the sanitised maintenance error and storage health. Do not keep restarting a damaged installation to clear readiness.

Manual unavailable or startup reports index corruption

manual_unavailable readiness503 means there is no available manual. Check manual_index matches the read-only mount and that UID65532 can read its directory/files. Install the approved prebuilt index, then restart within a maintenance window.

The index contains CURRENT and snapshot-<sha256>.json files. An existing directory with missing/invalid CURRENT, an absent target or corrupted snapshot may fail startup rather than return readiness503. Verify against the release's authenticated hashes; preserve existing retained snapshots/citations. Do not copy arbitrary manual text or run an importer inside the scratch image. Manual searches must work before installation acceptance.

TLS, issuer or client connection fails

  • Use the canonical dedicated origin, with no path prefix/trailing slash in public_origin. A probe to the loopback listener with the wrong Host may be rejected; do not change the issuer to loopback to make it pass.
  • Check certificate expiry, hostname and chain using your browser's certificate viewer or host TLS tools. For internal CAs, configure the approved trust bundle in MCP for outbound Canvus access and in local clients for ingress access. Do not use curl -k or turn TLS validation off.
  • Check discovery via /.well-known/oauth-authorization-server on the canonical origin and compare its issuer/endpoints with the administrator's origin. Verify the proxy preserves Host, Authorization and MCP headers, streaming and the whole origin's routes.
  • If local Code/Codex works but Claude remote connectors fail, check public HTTPS443 reachability from the cloud, not just your laptop VPN. Verify the provider's connector entitlement. Do not add an MT gateway as a workaround.
  • For callback mismatch, reconnect using the client's normal OAuth registration and exact permitted HTTPS/loopback callback. Do not use wildcard callbacks or confuse allowed_origins with callback registration. Never attach a callback URL containing authorization codes/state to a ticket.

Canvus requests fail or features are unavailable

Check the Canvus version against the MCP release's explicit supported minimum, not an arbitrary recent version. The minimum is 26.11.4, using the qualified combined container. Required capabilities are saved-demo-v1, model3dSTL-v1, library-atomic-v1 and the Canvus release's registered library_atomic_receipts_v1 migration. Ask the Canvus administrator to upgrade through that release's procedure; do not hand-apply SQL or replace atomic behavior with sequential writes.

A permission denial may be correct for your Canvus account. Confirm you can access the same content using your own Canvus client; do not test with another person's credentials or grant broader permissions just to silence an error. Expired/revoked authorization needs client reauthentication, not editing the state database. Changing the configured Canvus authority requires a planned identity transition.

For upload-limit errors, check the file size against max_upload_bytes, matching CANVUS_UPLOAD_MAX_BYTES and the proxy's limit. A proxy should allow the file cap plus multipart overhead; the ingress allows 1 MiB of multipart allowance. Current maximum file cap is 1 GiB, not an unlimited-upload promise.

A write timed out, or the key is lost

Do not resubmit a timed-out mutation as a new operation. Keep its operation ID privately and query the normal operation status/receipt path in the authenticated client; a transport error is not evidence that no change occurred. Do not restore an older database or delete consumed approvals. Follow Upgrading and recovery and escalate unresolved outcomes.

If the key is lost, stop recovery attempts that would overwrite state. Preserve the remaining files and locate a matching coordinated backup. A new random key cannot decrypt existing encrypted credentials.

Collect a small, nonsecret support case

Use the support route linked from the Apps home page, or your established MT support contact. Existing MultiTaction support arrangements apply; this release does not introduce a new SLA.

Provide:

  • MCP version and source identity from your retained release-manifest.json, image ID/digest and whether installation used archive or registry. Do not send a whole source checkout or a signed download redirect URL.
  • The actual running image ID, obtained locally with:
docker inspect --format '{{.Image}}' "$(docker compose -f compose.yaml ps -q canvus-mcp)"
  • If the container is running, its binary version (no shell required):
docker compose -f compose.yaml exec -T canvus-mcp /usr/local/bin/canvus-mcp version
  • Canvus/native versions from your administrator's installed-release record, and AI-client name/version from its About/version display. Include whether the client runs locally or in the cloud, and the timestamp, HTTP status and redacted error code.
  • Host OS/architecture, Docker/Compose versions and available disk capacity, obtained with your normal host tools. State whether an internal CA is used; do not attach private keys or the entire configuration/environment.
  • Only the necessary log lines from the short log command above, reviewed and redacted locally. Include health/readiness status and a minimal synthetic reproduction, not canvas payloads.

Do not attach passwords, tokens, OAuth query strings, encryption keys, state databases/backups, client registrations, grants, uploaded files, private certificates, manual text or customer canvas content. Keep operation IDs and other potentially sensitive identifiers private unless support requests them through an approved channel. There is no need to run a broad environment dump, submit a paid AI conversation or repeat the failed mutation to collect these facts.