Troubleshooting

Start with one failed request and a bounded time window. Record the environment, target, caller, status, safe reason code, and correlation identifier. Do not collect tokens or raw payloads in the investigation.

Follow the failure

Symptom	First check	Next action
Identity is rejected	Token verification or configured login boundary.	Check issuer, audience, expiry, and the expected authentication flow.
Administrative action is forbidden	Actor permissions and scope.	Inspect stored role bindings.
Tool is missing from discovery	Caller policy and approved tool set.	Simulate the intended identity and resource.
Tool call is denied	Decision reason and policy version.	Correct the specific failing boundary.
Credential resolution fails	Binding state, mode, target, and secret reference.	Verify secret-backend access from the runtime.
Upstream is unreachable	Approved endpoint, connector, DNS, transport.	Test the actual runtime route.
Runtime is unready	Dependency health and projection freshness.	Inspect delivery, validation, and acknowledgement.
Reconnect fails	Session expiry, revocation, and affinity.	Inspect session state; do not recreate revoked authority.
Audit query is empty	Scope, time range, and delivery state.	Broaden carefully and inspect audit transport.

Distinguish configuration from activation

If a policy or binding changed recently, compare the replica’s active projection with the desired configuration. Read runtime configuration delivery before repeatedly editing or restarting components.

Verify the correction

Repeat the original request with the same intended identity and inputs. Check the audit decision and a negative test that must remain denied. A fix is incomplete if it restores success by widening unrelated access.