Troubleshooting
Codes are the code of an error response or the reason_code of a decision. See API error codes.
Installing the SDK
| Symptom | Cause | Fix |
|---|---|---|
| 401 from the private SDK index | No SDK download token on this machine, or it expired or was revoked | Add 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 mismatch | The file isn't the one the command pinned | Use 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 registry | No .npmrc in the project, or PREWORLD_GUARD_SDK_NPM_AUTH isn't set | Commit .npmrc from .npmrc.example; set the variable to the base64 of token:<SDK download token> |
npx preworld-guard downloads something | npx without --no fetches from the public registry when the SDK isn't installed | Always 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] conflict | Run the MCP proxy or the broker in its own environment |
The wizard won't offer a framework, or SDK_ADAPTER_UNAVAILABLE | The SDK version the wizard installs has no adapter for it yet | Check 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
| Check | Common causes | Fix |
|---|---|---|
| Credential active | guard.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 online | The 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 loaded | The executor hasn't fetched the current version yet ("Not confirmed"), or runs an older one | Wait for the next heartbeat (about 15 seconds). If it stays, check the executor's last error on "Executors" |
| First event received | The agent hasn't made a guarded call yet | Run one call through a wrapped tool. If events stay queued, see Every action is blocked |
Any check, AGENT_CREDENTIAL_MISMATCH or EVENT_AGENT_MISMATCH | The agent ID in the code differs from the connection's | Use PREWORLD_GUARD_AGENT_ID from guard.env |
| Events stop and the agent is blocked with 403, several agents on one machine | SDK 0.8.0 and earlier shared one event queue between agents started from the same folder | Upgrade to 0.9.0, or give each agent its own PREWORLD_GUARD_CACHE |
Every action is blocked
| Symptom | Cause | Fix |
|---|---|---|
GUARD_UNAVAILABLE (or a GuardError from @guard.tool) after the control plane was unreachable | More than 5 minutes without a successful policy refresh | Restore 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 expired | Rotate the connection and restart with the new package. The SDK never falls back to the cache after a 401 or 403 |
POLICY_EXPIRED | The policy's expires_at has passed | Publish a policy without it, or with a later time |
GUARD_AUDIT_UNAVAILABLE | The local event queue is full, often because events can't be sent | Fix the connection to the control plane. Check the queue's folder has space |
DEFAULT_DENY on everything after switching to Enforce | default_effect: deny with no allow rule for these actions | Add allow rules, or go back to Observe and generate a candidate from observed behaviour |
SUBJECT_REQUIRED | A rule compares an argument with the trusted subject, and the call has none | Pass the user with guard_run(subject_id=...) or the adapter's resolve |
Publishing is refused
| Message or code | Cause | Fix |
|---|---|---|
POLICY_V2_NEEDS_EXECUTORS | A format v2 policy, and an active executor doesn't support format v2 | Upgrade that agent's SDK, or retire executors you no longer use on "Executors" |
CANDIDATE_BASE_OUTDATED | Another version was published while this candidate was in review | Draft again from the current version and submit it for review |
POLICY_REVIEW_BY_AUTHOR, POLICY_REVIEW_SAME_SUBJECT | The author, or the same trusted subject, tried to review | Another person with the reviewer role reviews it |
POLICY_REVIEW_NEEDS_REVIEWER | An admin tried to approve a policy review | Only the reviewer role approves policy reviews |
CANDIDATE_HASH_MISMATCH | The policy differs from what was reviewed | Publish the reviewed candidate as it is, or submit the changed one for review |
CANDIDATE_EXPIRED, CANDIDATE_NOT_APPROVED_OR_EXPIRED | The candidate's time ran out | Save it again as a new candidate |
CANDIDATE_NO_OBSERVED_ACTIONS | Nothing reached the threshold in the observation window | Lower the minimum count, widen the window, or let the agent run longer |
POLICY_DSL_INVALID | The YAML has errors | Click 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
| Symptom | Cause | Fix |
|---|---|---|
APPROVAL_SUBJECT_REQUIRED | The call has no trusted subject | Pass it with guard_run(subject_id=...). For the MCP proxy, start it with --subject-id |
APPROVAL_NOT_CONSUMABLE on resume | The ticket was used, expired, rejected, or the arguments differ from what was approved | Request a new approval. Don't let the model change the arguments of a call that waits for approval |
POLICY_CHANGED | The policy changed while the ticket was being filed | Propose the call again under the new policy |
The reviewer gets TICKET_SELF_APPROVAL | The action's trusted subject is the reviewer | Another reviewer decides |
| An MCP client keeps getting "approval required" after approval | The client can't send _meta on the retry | Use a client that can pass _meta, or a framework adapter |
A snapshot stays uncertain | The process stopped after it started running the call | Check the business system. Guard never replays it automatically |
MCP proxy
| Symptom | Cause | Fix |
|---|---|---|
| A tool doesn't appear in the agent's list | The policy doesn't admit it, it isn't in allowed_tools, or its metadata changed and it is frozen | Check the policy for mcp.admit, the registry, and approve the new metadata with mcp-manifest |
| The proxy won't start with an HTTP downstream | An upstream's origin isn't approved yet | Run 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 proxy | Remove them, or use --downstream-transport streamable-http with --config |
| HTTP 421 from the proxy | The Host isn't in --allowed-host | Add the Host name the agent really uses |
The proxy fails at start-up with --sandbox | srt isn't installed, or isn't version 0.0.77 | Install 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.