AI Translation Notice
Translated/synchronized from the authoritative Chinese documentation (部署与运行排错 FAQ). Check source files or Chinese docs if subtle phrasing differs.
Deployment & Runtime FAQ
This page covers concrete runtime errors and operational diagnostics. For pre-adoption architecture/selection questions, see README.en.md. Always redact secrets, host paths, file contents, and command outputs before sharing logs.
Connector Connectivity & 503 Errors
Status.cmdshows the local connector running, yet/healthzor/mcpreturns503?BridgeRelayenforcesFIRST_HEARTBEAT_GRACE(10s) andHEARTBEAT_MAX_AGE(65s). Checkconnector-status.jsonin%USERPROFILE%\.agentdock-bridge, verify proxy reachability (HTTPS_PROXY/ Windows WinINet), and confirmBRIDGE_TOKENmatches between DPAPI storage and Cloudflare Secrets.409 A connector is already online or completing its heartbeat? Only one live/bridgesocket is allowed at a time. Wait up to 65s for the dropped socket's heartbeat window to expire, or stop the existing host process viaStop.cmd.
Local Approvals & Replay Protection
- Why does every retry still return
LOCAL_APPROVAL_REQUIRED? Approvals expire after 5 minutes and bind exactorigin, client identity, scopes, method, and all arguments (excluding only client JSON-RPCid). Changing path, offset, content, ornetwork: "outbound"invalidates the match and queues a new pending record (caps:64global /8per client). - What triggers
APPROVAL_RECORD_TOO_LARGE?approval-store.mjsenforces a1,200,000-byte UTF-8 ceiling on the compact JSON.request.jsonrecord before creating any temp file. Split large writes/edits or trim excessive client metadata. - Why does retrying after a
504timeout fail withalready_attempted? Sensitive calls unlink.approved.jsonand claim a 24-hour entry inRequestReceiptsbefore running the container. A110stimeout cannot prove nothing executed, so replay is blocked by design. Inspect workspace/command state via read-only tools orcommand_status, then submit a fresh RPC if needed.
Windows Host ACLs & Docker Failures
Assert-PrivateStateorAssert-WriteProtectedPathblocks startup or installation?State-Safety.ps1inspects%USERPROFILE%\.agentdock-bridge,%USERPROFILE%\.agentdock-toolchains, and every ancestor directory, rejecting symlinks/junctions, multiple hard links (Links !== 1), or unexpected write/modify ACEs (such as leftover sandbox user ACEs). Inspect ancestor permissions and remove unexpected principals.- Why do
edit_fileandwrite_file(overwrite=true)refuse certain files on Windows? Container-siderenameover a Windows bind mount can strip custom NTFS DACLs.local/windows-acl.mjsblocks replacement whenever explicit non-inherited ACEs, protected ACLs, or a different file owner are detected; edit those files natively on Windows. - What does
cleanup_confirmed: falsemean and why are new commands rejected afterward? Whendocker rm -ffails with anything other thanNo such container/object, the sandbox setsclosed = true, blocking all new file and command calls while keepingcommand_statusandstop_commandopen for the owning client. Inspectdocker ps -a, fix Docker Desktop, and restart viaStop.cmdthenStart.cmd.
OAuth Sessions & Cross-Platform Tests
Refresh credential reuse detected. Connect again.? Submitting a previously rotated (spent) refresh token revokes the entire grant family inAuthStore. Reconnect the MCP client usingPassword.cmd(or wheneverRotate-Secrets.ps1updatesOWNER_PASSWORD_HASH).- Why does
pnpm testskip 15 tests on Linux or macOS? Windows DPAPI (secret-process.test.mjs), NTFS ACL (windows-acl.test.mjs), PowerShell supervisor checks (management-safety.test.mjs), and real Docker integration (sandbox.test.mjswithoutAGENTDOCK_DOCKER_TEST) auto-skip when host prerequisites are absent.