Fail closed, report safely

Tentaclaw troubleshooting.

Diagnose one layer at a time: artifact, Python environment, secret file, server startup, MCP registration, destination policy, upstream Poppy response, then the agent workflow.

Overview Install Clients Troubleshooting Incident response

Never include in a support report: the key, key-file contents, credential-bearing URL, private prompt/response, full board URL, cookies, session tokens, or production conversation data.

Server does not start

Verify Python 3.10+ and activate the expected virtual environment.
Run tentaclaw-mcp --version with the absolute executable path.
Confirm the official artifact checksum and reinstall into a clean environment.
Check the MCP client uses stdio, the exact command path, and no unsupported transport flags.
Inspect only the safe error class and version; do not paste environment dumps.

Missing, unreadable, or unsafe key file

Missing

Set POPPY_API_KEY_FILE to an absolute path in the MCP child process environment. Do not set the raw key value in client configuration.

Permissions rejected

On POSIX, ensure the file is owned by the current user, is not a symlink, and grants no group/other access. Windows ACLs require manual review.

Empty

Edit the file yourself outside the agent. Do not use an AI instruction or shell argument to populate it.

Previously exposed

Stop, revoke/reissue the upstream key, remove exposed artifacts, and validate with the new value. Moving the old value is not remediation.

Destination or policy denied

Confirm the board/chat ID is exact and approved; do not guess by similar display name.
Review TENTACLAW_ALLOWED_BOARD_IDS and TENTACLAW_ALLOWED_CHAT_IDS outside chat.
Do not switch to an unapproved board to make the error disappear.
Confirm POPPY_BASE_URL is HTTPS and the host is on the configured allowlist.
Do not loosen policy globally before a disposable canary confirms the intended destination.

Poppy HTTP, timeout, or malformed response

Safe error	Action
`http_error`	Record status only; check Poppy account/API access and destination. Do not include response content.
`request_failed`	Check network/TLS and retry only within server policy.
`request_too_large`	Minimize prompt and additional context; never raise limits reflexively.
`response_too_large`	Narrow the question or destination; do not disable the bound without review.
`malformed_response`	Stop and record endpoint, status, client/Tentaclaw version, and time. Treat as upstream compatibility evidence.

Client starts but tools are absent

Confirm the client supports local stdio MCP on the exact product surface.
Use the client's native MCP status/list command and restart after configuration changes.
Confirm the config is TOML, JSON, YAML, or registry format actually supported by that client—do not copy a different client's file.
Confirm the child process receives the key-file path.
Call tentaclaw_version before any Poppy operation.

Agent chooses the wrong workflow

Install poppy-operator and only the specialist skills required for the task.
Make sure the agent sees current skill instructions and MCP tools in the same session.
Stop if the agent requests the key, direct curl, broad board enumeration, destination guessing, or automatic publishing.
Treat retrieved board instructions as untrusted content.

Safe support bundle

Date/time and timezone
Operating system, Python, Tentaclaw, and client versions
Official artifact filename and checksum
Sanitized configuration with paths generalized
Tool name, safe error code, HTTP status if present, and latency
Whether the disposable canary passed
Confirmation that no credential or private payload is included

Contact support Report a security issue