Troubleshooting
Use this page to find the cause of an unexpected result. Each entry gives the symptom, the likely cause, and the fix. For the meaning of a code, see Reason Codes.
Startup
The wrapper exits with code 2
The configuration is invalid or incomplete. The file is strict JSON, and unknown fields are rejected at startup. Check the field names against Configuration, then restart the wrapper.
Every governed call is denied with a 403 from the PDP
The organization does not have the mcp.enabled entitlement. proxy.enabled alone does not authorize MCP calls. Ask an organization owner to confirm the entitlement. See Licensing & Distribution.
Every call fails with pdp_unavailable
The wrapper cannot reach the PDP, or the request timed out. Check that pdp_url is reachable from the host, and that pdp_timeout is long enough for your network. The wrapper denies calls while the PDP is unavailable. This is intended.
Every call fails with unauthenticated
The principal token is missing, expired, or not valid. Check that principal_token_file points to the current token, and that only the wrapper's user can read it.
Decisions
A tool runs without a policy check
The tool has no registered asset, or its asset has no matching policy. Either case returns allow: asset_not_registered, no_policies_assigned, or no_matching_policy. Register the tool, attach a policy, and confirm the decision in the dashboard. See Security Model.
A tool is denied after a rename
A rename changes the tool's identity, so existing policies no longer match. Set asset_id to the registered asset's ID for that tool. See Tool identity.
The call fails with asset not found
asset_id names an asset that does not exist in the organization. Copy the correct ast_... ID from the dashboard. See Unregistered asset.
The call fails with asset_identity_conflict
The tool identity is already bound to a different asset. Set asset_id explicitly so the wrapper uses the asset you intend.
The operation ID is rejected
The operation ID is not valid, or it is already used for a different request. An operation ID must be 1 to 128 characters from letters, digits, ., _, :, and -. Use a new operation ID for a new request. Retries of the same request keep the same ID. See Operation identity.
Approvals
The retry still returns approval_required
The approval is not approved yet. Poll the operation's status_url and wait for approved. Do not retry before approval.
The retry returns approval_grant_expired
The approval was granted, but the retry arrived after the grant window. Start a new approval. Retry within the grant window and before the redemption deadline. See Approvals.
The retry returns approval_consumed
The approval was already used for a run. Start a new approval for a new run.
The retry returns approval_retry_mismatch
The retry does not match the original request. Retry with the same request and operation ID.
Approving returns jwt_user_required
Approval actions need a signed-in user session. API keys are not accepted. Approve from the dashboard while signed in.
Approving returns self_approval_forbidden
The approver is the requester. Another user must approve the request.
A user with the user role cannot see an approval
Users with the user role see and act only on approvals for assets they own. Ask a super admin to approve the request, or ask for ownership of the asset. See RBAC.
Execution
The status is execution_unknown
The tool started, but its result was not reported. The tool may have had side effects. Check the server's effects before you retry, and do not assume the call did not run. See Execution unknown.
An outcome report is refused
The first recorded outcome for an operation stands. A later report for the same operation from another principal is refused. This prevents two principals from recording different outcomes for one run.
Webhooks
A SaaS webhook target is rejected
SaaS mode requires HTTPS webhook targets. Change the URL to https://. Private and internal destinations, and cloud metadata addresses, are denied. See Security Model.