Skip to content

Troubleshooting ​

Codes are the code of an error response or the reason_code of a decision. See API error codes.

Installing the SDK ​

SymptomCauseFix
401 from the private SDK indexNo SDK download token on this machine, or it expired or was revokedAdd the ~/.netrc line from the console (mode 600), or issue a new token. In CI, point NETRC at a temporary file
pip reports a hash mismatchThe file isn't the one the command pinnedUse the exact command from the console. Don't change the version or the address by hand
npm can't find @preworld/guard, or tries the public registryNo .npmrc in the project, or PREWORLD_GUARD_SDK_NPM_AUTH isn't setCommit .npmrc from .npmrc.example; set the variable to the base64 of token:<SDK download token>
npx preworld-guard downloads somethingnpx without --no fetches from the public registry when the SDK isn't installedAlways run npx --no preworld-guard … from the folder where @preworld/guard is installed
An extra won't install next to another one[crewai,mcp] and [google-adk,gateway] / [google-adk,oauth] conflictRun the MCP proxy or the broker in its own environment
The wizard won't offer a framework, or SDK_ADAPTER_UNAVAILABLEThe SDK version the wizard installs has no adapter for it yetCheck the minimum SDK version for that framework in Framework adapters. The wizard offers a framework only when the SDK it installs has its adapter

The connection check fails ​

CheckCommon causesFix
Credential activeguard.env not loaded, or the connection was revoked or rotated, or the credential expired (RUNTIME_TOKEN_INVALID)Load the variables into the agent's environment. After a rotate, use the new package and restart the agent
Executor onlineThe agent isn't running, guard.start() isn't called, or no heartbeat for 2 minutes ("Lost contact")Start the agent with guard.start(). If it must go through a company proxy, set PREWORLD_GUARD_PROXY (and PREWORLD_GUARD_CA_BUNDLE); the SDK ignores HTTPS_PROXY
Current policy loadedThe executor hasn't fetched the current version yet ("Not confirmed"), or runs an older oneWait for the next heartbeat (about 15 seconds). If it stays, check the executor's last error on "Executors"
First event receivedThe agent hasn't made a guarded call yetRun one call through a wrapped tool. If events stay queued, see Every action is blocked
Any check, AGENT_CREDENTIAL_MISMATCH or EVENT_AGENT_MISMATCHThe agent ID in the code differs from the connection'sUse PREWORLD_GUARD_AGENT_ID from guard.env
Events stop and the agent is blocked with 403, several agents on one machineSDK 0.8.0 and earlier shared one event queue between agents started from the same folderUpgrade to 0.9.0, or give each agent its own PREWORLD_GUARD_CACHE

Every action is blocked ​

SymptomCauseFix
GUARD_UNAVAILABLE (or a GuardError from @guard.tool) after the control plane was unreachableMore than 5 minutes without a successful policy refreshRestore the connection; decisions resume at the next refresh. max_stale_age sets the limit
GuardAuthError, or the executor shows "Credential no longer valid"The credential was revoked or expiredRotate the connection and restart with the new package. The SDK never falls back to the cache after a 401 or 403
POLICY_EXPIREDThe policy's expires_at has passedPublish a policy without it, or with a later time
GUARD_AUDIT_UNAVAILABLEThe local event queue is full, often because events can't be sentFix the connection to the control plane. Check the queue's folder has space
DEFAULT_DENY on everything after switching to Enforcedefault_effect: deny with no allow rule for these actionsAdd allow rules, or go back to Observe and generate a candidate from observed behaviour
SUBJECT_REQUIREDA rule compares an argument with the trusted subject, and the call has nonePass the user with guard_run(subject_id=...) or the adapter's resolve

Publishing is refused ​

Message or codeCauseFix
POLICY_V2_NEEDS_EXECUTORSA format v2 policy, and an active executor doesn't support format v2Upgrade that agent's SDK, or retire executors you no longer use on "Executors"
CANDIDATE_BASE_OUTDATEDAnother version was published while this candidate was in reviewDraft again from the current version and submit it for review
POLICY_REVIEW_BY_AUTHOR, POLICY_REVIEW_SAME_SUBJECTThe author, or the same trusted subject, tried to reviewAnother person with the reviewer role reviews it
POLICY_REVIEW_NEEDS_REVIEWERAn admin tried to approve a policy reviewOnly the reviewer role approves policy reviews
CANDIDATE_HASH_MISMATCHThe policy differs from what was reviewedPublish the reviewed candidate as it is, or submit the changed one for review
CANDIDATE_EXPIRED, CANDIDATE_NOT_APPROVED_OR_EXPIREDThe candidate's time ran outSave it again as a new candidate
CANDIDATE_NO_OBSERVED_ACTIONSNothing reached the threshold in the observation windowLower the minimum count, widen the window, or let the agent run longer
POLICY_DSL_INVALIDThe YAML has errorsClick an error in the editor to jump to its line

Previews say "Not enough information" ​

The control plane only has argument names, not values, so rules on argument values can't be judged from events. That is expected. To check them, download the candidate and run preworld-guard policy-replay on your side. See Replay on your side.

Approvals ​

SymptomCauseFix
APPROVAL_SUBJECT_REQUIREDThe call has no trusted subjectPass it with guard_run(subject_id=...). For the MCP proxy, start it with --subject-id
APPROVAL_NOT_CONSUMABLE on resumeThe ticket was used, expired, rejected, or the arguments differ from what was approvedRequest a new approval. Don't let the model change the arguments of a call that waits for approval
POLICY_CHANGEDThe policy changed while the ticket was being filedPropose the call again under the new policy
The reviewer gets TICKET_SELF_APPROVALThe action's trusted subject is the reviewerAnother reviewer decides
An MCP client keeps getting "approval required" after approvalThe client can't send _meta on the retryUse a client that can pass _meta, or a framework adapter
A snapshot stays uncertainThe process stopped after it started running the callCheck the business system. Guard never replays it automatically

MCP proxy ​

SymptomCauseFix
A tool doesn't appear in the agent's listThe policy doesn't admit it, it isn't in allowed_tools, or its metadata changed and it is frozenCheck the policy for mcp.admit, the registry, and approve the new metadata with mcp-manifest
The proxy won't start with an HTTP downstreamAn upstream's origin isn't approved yetRun mcp-origin and approve it
--allowed-host/--allowed-origin 只适用于 streamable-http 下游。 (the CLI's message: these options only apply to a streamable-http downstream)Host or Origin options on a stdio proxyRemove them, or use --downstream-transport streamable-http with --config
HTTP 421 from the proxyThe Host isn't in --allowed-hostAdd the Host name the agent really uses
The proxy fails at start-up with --sandboxsrt isn't installed, or isn't version 0.0.77Install the pinned version and run preworld-guard sandbox verify

Still stuck ​

Run preworld-guard diagnose --output guard-diagnostics.json, then reach us through our contact page and we'll ask for the file. It contains no argument values, environment values or secrets.