ArmorPay Troubleshooting

PolicyBlockedException on a call you expected to succeed

Cause: The resolved enforcementAction for that tool/member is block or deny. Check, in order: a toolEnforcement override for that tool, the member's enforcementAction, then the policy's defaultEnforcementAction - see Concepts.

Fix: Adjust the rule in the Policy Studio, or apply a less restrictive bundle template (for example, move an AP Agent from Restricted AP Controls to Standard AP Controls).

PolicyHoldException even with waitForApproval: true

Cause: The poll window (holdPollIntervalMs × holdPollAttempts) expired before an approver acted on the delegation.

Fix: Increase the poll window, or resolve the delegation from the plan view faster. Direct-client ArmorPay integrations have a shorter delegation window than framework-wrapped (ADK) integrations, so build an on-call or notification path for approvers rather than relying on a long-lived poll.

Amount threshold doesn't trigger a hold

Cause: amountThreshold.requireApprovalAbove only describes a number - it does not by itself set the enforcement action. The rule also needs enforcementAction: hold (or a toolEnforcement entry) for a breach to actually hold the call.

Fix: In the Policy Studio's Amount Threshold section, confirm the Approval Workflow field is set, or add an explicit tool-level override in Tool Configuration.

Applying a bundle didn't change anything for the agent

Cause: Bundle apply is upsert-by-name and clean-slate - it deactivates the agent's existing active policy before importing the new one. If the import itself failed (invalid YAML, missing orgId), the backend can leave the previous policy deactivated with the new one not active.

Fix: Re-open the bundle in the Policy Studio and click Deploy Policy again; check the deploy confirmation for a per-policy error rather than assuming a 200 response means it landed.

Vendor/recipient always blocked even though it's approved

Cause: recipientValidation.approvedVendors is an explicit allow-list. An empty list combined with blockNewRecipients: true blocks every recipient, not just unknown ones.

Fix: Add the vendor name (or ID, depending on how your AP agent's tool exposes it) to approvedVendors in the Recipient Validation section.

No trace shows up for a call I know happened

Cause: Observability is telemetry, not enforcement - a shipping failure never blocks or changes the tool call, so a missing trace doesn't mean the call didn't run.

Fix: See the shared observability troubleshooting guide for missing sessions, delayed traces, and agent-name mismatches. Confirm observability.enabled wasn't set to false on the client (see Observability).

Draft in the Policy Studio disappeared

Cause: Drafts persist to browser localStorage, scoped to that browser/profile. Clearing site data, switching browsers, or using a private window loses the draft.

Fix: Deploy the policy before switching environments, or keep a copy of the exported YAML.