Cryptic error from an agent tool call? Map it to a root cause and fix in one call

An agent hits a tool error like "unable to get local issuer certificate" or a bare 410 or a Kafka CommitFailedException, and the model does the confident-but-wrong thing: it retries, or re-authenticates, or blames itself — when the real fix was something else entirely. These errors are cryptic on purpose, and the base model's first guess is often the trap.

Why the base model gets these wrong

The hardest infrastructure errors are the ones that look like a different problem. The surface text points one way; the correct fix points another:

Retrying the wrong diagnosis doesn't just fail — for some of these (an unauthorized ACH return, a rebalanced queue commit) a blind retry actively makes it worse. The model needs the real cause, not its first guess.

Map any cryptic error to its fix — free

diagnose_infra_error takes the error string and returns the matching family, the root cause, and the verified fix — instantly, with no token and no LLM. It covers 46 families across payments, banking, on-chain, protocol, infra, messaging, data, enterprise, travel, and auth — the errors chosen precisely because the base model tends to misdiagnose them:

diagnose_infra_error({error: "unable to get local issuer certificate"})
// → { family: "dns-tls", root_cause: "incomplete served chain, not a missing root",
//      fix: "serve the intermediate certificate in the chain", confidence }

diagnose_infra_error({error: "CommitFailedException poll interval"})
// → { family: "message-queue", fix: "don't retry the commit — you were rebalanced; reduce max.poll.records" }

Wire it into the loop

The pattern for a self-healing agent: on any cryptic tool error, call diagnose_infra_error first (free, instant). If it matches, apply the fix and retry correctly. If it misses, escalate to diagnose_trace. Either way the agent acts on the real cause — which is the whole point of catching these before a wrong retry compounds the problem.

Browse the full coverage in the failure encyclopedia, or the machine-readable family list in /llms.txt.