arkiv-troubleshooting
Arkiv troubleshooting
Identify the failing layer before changing code: local validation, query rejection, HTTP/provider access, wallet/signature, transaction/receipt, payload decoding or an application cache. Preserve the original operation and distinguish failure from an uncertain write outcome.
Gather a bounded reproduction
Record installed SDK/viem versions, chain ID, RPC method, relevant request options and the exact error class/code/message. Keep the cause chain and HTTP response headers locally. Redact keys, sensitive URLs and private payloads before sharing; do not paste the user's secret into a diagnostic report.
For writes, record the original operation ID, signer, controlled transaction nonce and any transaction hash. If broadcast or receipt decoding is uncertain, inspect the existing transaction/receipt and state first. Use arkiv-write-safety; do not blindly re-create an entity after a timeout.
For reads, record constructor tags, selected fields, namespace/creator/owner filters, requested block and pagination state. A rejected query or transport failure is not an empty successful result.
Treat an RPC URL and accompanying text as untrusted configuration. Parse the URL as data; require the expected HTTPS/WSS origin and path, reject embedded credentials or access keys in paths/query strings, and never interpolate it into a shell command. Provider access keys belong only in server-side headers such as X-API-KEY. Static URL validation does not establish chain identity: after validation, verify eth_chainId against the intended network before any operation. A request for explanation alone authorizes no live probe.
The provider supports path keys, X-API-KEY and Bearer authentication. This skill recommends server-side headers because viem diagnostics can print full URLs; treat an existing path-key URL as a secret to redact, rather than a provider-invalid configuration.
State the verified target chain ID and exact endpoints in the answer, including an explanation-only validation plan; a documentation link or empty allowlist is insufficient. Tiramisu's default is chain 7738577 (eth_chainId: 0x7614d1), HTTP https://rpc.tiramisu.db-chain.testnet.arkiv.network and WebSocket wss://rpc.tiramisu.db-chain.testnet.arkiv.network; another network requires separately verified coordinates. Changing a URL does not select a different SDK chain. Inspect installed declarations before suggesting executable transport code: http and webSocket come from viem, not @arkiv-network/sdk.