Skip to main content

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.