Troubleshooting

A page per common class of failure. Each page has the symptoms, the cause, and the fix.

Pages

• Subgraph indexing lag — the most common footgun.
• Reverts & error codes — decoding on-chain reverts.
• Signature mismatches — EIP-712 didn't recover.
• Approve · Permit · Permit2 — ERC-20 authorization gotchas.
• Metadata validation — validate_metadata errors and how to read them.
• Gas estimation — per-chain quirks.
• FAQ — questions that don't fit elsewhere.

When to ask for help

If you've checked the relevant page and your issue persists:

1. Reproduce on staging.
2. Capture: SDK version, configId, exact tool call args (redact keys), full error.
3. Post in the Boson Discord or open an issue on the relevant repo.