Troubleshooting

Every failure MAP produces carries a typed error code. Find yours below: cause first, then the fix.

Policy decisions (not errors)

These are policy outcomes, not bugs. Your action was evaluated and decided:

Code	Cause	Fix
`policy_denied`	A `deny` rule matched	Read `reason` and `policy_checks` in the receipt; adjust the action or the rule
`approval_required`	A rule returned `require_approval`	Call `POST /approve` with the approval reference, or wire `onApprovalRequired`
`approval_denied`	A human rejected the approval	Expected path - surface it to the requester
`approval_expired`	The approval window lapsed before use	Re-request approval; shorten nothing, lengthen `approval_timeout` if legitimate

Approval lifecycle

Code	Cause	Fix
`approval_expired`	Reference used after expiry	Dispatch again for a fresh reference
`idempotency_conflict`	Same idempotency key replayed with a different payload	Reuse the exact original payload, or mint a new key

Identity and tokens

Code	Cause	Fix
`invalid_delegation_token`	Malformed or tampered token	Re-issue from the delegating agent
`token_expired`	Token past its time window	Re-issue; check clock skew beyond the ±5 minute signing window
`token_invalid_signature`	Signature doesn't verify	Wrong key, wrong `kid`, or canonicalization drift - compare against the conformance fixtures
`token_missing_scope`	Token lacks the capability being attempted	Re-issue with the capability in scope
`tenant_mismatch`	Request tenant differs from token/resource tenant	Scope the request to one tenant; enable `MAP_REQUIRE_TENANT=true` to fail fast
`unauthorized` / `forbidden`	Missing or insufficient credentials	Check signing secret, `MAP_ADMIN_TOKEN` for admin routes

Agents and capabilities

Code	Cause	Fix
`agent_not_found`	Unknown `target_agent`	`GET /agents` to list registered agents
`agent_disabled`	Agent administratively disabled	Re-enable or route to a standby agent
`capability_not_found`	No handler for the capability	Register it (`agent.can(...)`) or fix the name
`capability_disabled`	Handler registered but disabled	Re-enable
`resource_not_found`	Referenced task/receipt/agent ID doesn't exist	Verify the ID; check tenant scoping

Schema and protocol

Code	Cause	Fix
`schema_validation_failed`	Request body fails MAP JSON Schema	Validate locally first; check `requested_schema_version`
`schema_version_unsupported`	Server doesn't speak the requested version	Negotiate: omit the version or use a supported one
`schema_negotiation_failed`	No common version found	Upgrade the older side
`invalid_request`	Malformed envelope or missing fields	`task_id`, `target_agent`, and `intent` are required

Reliability

Code	Cause	Fix
`rate_limit_exceeded`	Too many dispatches	Back off; batch with `dispatchBatch`; raise limits server-side
`request_timeout`	Handler or downstream exceeded deadline	Prefer `delivery_mode: 'async'` for long tasks; poll or stream status
`internal_error`	Server-side failure	Check server logs and `/health`; dead-lettered async tasks are inspectable and replayable

Still stuck?

Run the demo locally to isolate client vs server issues
Query GET /audit-events - every decision leaves a signed trail showing which rule fired
Check the conformance harness to verify your client against the reference contract