ArmorHealth Troubleshooting

PolicyBlockedException / PolicyHoldException on a routine read

Cause: The resolved enforcementAction for that tool is stricter than expected. Check, in order: a toolEnforcement override for that tool, the member rule's enforcementAction, then the policy's defaultEnforcementAction - see Concepts.

Fix: Adjust the rule in the Policy Studio, or move to a less restrictive bundle (for example, from HIPAA-Strict Risk Assessment to Standard Risk Screening).

Held site-of-care or referral action never resolves

Cause: propose_oon_referral, schedule_appointment, and similar site-of-care actions are held by design in most bundle templates so a human confirms the recommendation. If no approver acts within the client-side poll window, the SDK call raises rather than waiting indefinitely.

Fix: Confirm Approver Roles and Approval Channels are configured in the Delegation Approval section, and resolve the delegation from the plan view. ADK-based ArmorHealth integrations poll longer than ArmorPay's direct-client integrations, but that window is still finite.

PHI access blocked even for an authorized care agent

Cause: phiAccess.maxRecordsPerQuery or allowedDataCategories is narrower than the query the agent is issuing - this is the PHI Access Control section enforcing minimum-necessary access, not a bug.

Fix: Widen maxRecordsPerQuery or add the missing data category in the Policy Studio, or split the agent's query into smaller, in-bounds requests.

Claim auto-approved when you expected manual review

Cause: The claim amount is below claimProcessing.autoApproveBelow. Auto-approve and manual-review thresholds are independent cutoffs, not a sliding scale - a claim under the auto-approve line skips review even if it's close to the manual-review line.

Fix: Lower autoApproveBelow, or move the agent to a bundle where auto-adjudication is disabled (for example, Restricted Claims Access instead of Standard Claims Access).

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 failed (invalid YAML, missing orgId), the previous policy can end up deactivated without the new one active.

Fix: Re-open the bundle in the Policy Studio and click Deploy Policy again; check the deploy confirmation for a per-policy error.

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.

Fix: See the shared observability troubleshooting guide. Confirm observability.enabled wasn't set to false on the underlying client (see Observability).

Draft in the Policy Studio disappeared

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

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