Error codes
A consolidated reference for every error code you might see, across the surfaces: the dig RPC (JSON-RPC), the dig-store CLI (process exit codes), DIGHUb (the web app's user-facing codes), and the chia:// content loader (the DIG Browser / extension). Look up the code you got; each row says what it means and what to do.
For step-by-step fixes, see Troubleshooting.
Machine-readable
This catalog is also published as error-codes.json — a flat [{surface, code, http_or_exit, description}] list (plus a bySurface index) so an agent can branch on a code without scraping this table. It is generated from the same source as the tables below and drift-checked against them on every build, so the two can never disagree.
dig RPC (JSON-RPC)
The dig RPC uses the standard JSON-RPC 2.0 error codes plus the protocol-specific -32004, -32005, the node-profile -32003 / -32006 / -32007 / -32008 / -32009, the shell/staging codes -32010 (upstream) and -32011–-32014 (dig.stage), the metadata-response bound -32015 (dig.getMetadata), the push-reassembly bound -32016 (cache.pushCapsule), the private-retrieval codes -32020 / -32021 / -32022, the local control-plane codes -32030 / -32031 / -32032, and the wallet chain-read/broadcast codes -32040–-32043. A content miss is never an error — the capsule returns its own indistinguishable, non-verifying response (there is no decoy field on the wire), and the client discovers the miss by inclusion-proof and/or decryption failure (see the blind host model). For any well-formed body the HTTP status is 200; the error is carried in the JSON envelope.
| Code | Meaning | What to do |
|---|---|---|
-32700 | Parse error — the request body isn't valid JSON. | Fix the JSON you're sending; ensure Content-Type: application/json. |
-32600 | Invalid request — not a request object/array, an empty batch, or a missing method. | Send a valid JSON-RPC request with a method field. |
-32601 | Method not found — this node doesn't implement the method. | Check the name against Methods; call dig.methods to see what the node supports. |
-32602 | Invalid params — missing/malformed store_id, root, or retrieval_key, or "latest" on a store with no confirmed generation. | Verify each identifier is the right length of lower-case hex; confirm the store has at least one capsule. |
-32603 | Internal error — the node failed to satisfy a well-formed call. | Retry; if it persists, try another node or report it. |
-32003 | Content miss rate limited — this node does not hold the requested content, and this requestor is driving the miss → provider-lookup path too fast. A per-requestor token bucket (burst 16, refill 4/s) fronts the DHT lookup and the proxy fetch, keyed by requestor identity (mTLS peer_id / connection IP / a shared loopback bucket); over budget the miss is refused with this code, while a different requestor draws from its own bucket and is unaffected. A well-formed error, never a silent empty success. Returned by the node-profile content methods (dig.getContent, dig.fetchRange) on a rate-limited miss. | Back off and retry the same request after a short delay — it is transient (distinct from the holder-fatal -32009). Slow your miss/lookup rate; a caller that names concrete content it actually wants stays under budget. |
-32004 | Resource not available at the requested root — a genuine infrastructure miss (no host seed, the module absent in both buckets, bad magic, oversize, a wasmtime trap, or an undecodable envelope). Distinct from a content miss, which is an indistinguishable decoy and is never an error. | Confirm the root is a confirmed generation (dig.listCapsules); retry or try another node. |
-32005 | Root not chain-anchored — the requested or served generation is not the store's current on-chain root. A content read is pinned to the CHIP-0035 singleton's on-chain root (resolved live from the chain, never trusted from the serving node): if the requested root is not the on-chain root, or the chain cannot be reached, or the store has no confirmed generation, the read fails closed with this code rather than serving an unverified generation. | Read against the store's current on-chain root (omit root to take the chain tip, or resolve it yourself); if the chain was unreachable, retry. |
-32006 | Peer unreachable — no connection to the named peer could be established: every NAT-traversal strategy (direct, UPnP/NAT-PMP/PCP mapping, relay-coordinated hole-punch, and relayed fallback) failed, or the peer is not registered on this network. Returned by the node-profile peer methods (dig.getPeers / dig.announce / dig.getNetworkInfo). | Confirm the peer is online and on the same network; retry — a relayed path may become available, or a hole-punch may succeed on a later attempt. |
-32007 | Range not satisfiable — the requested byte range lies outside the resource (offset ≥ its length) or is otherwise unsatisfiable. Returned by the node-profile dig.fetchRange (the streaming byte-range / multi-source content fetch). | Re-request within total_length (read it from any range frame or dig.getMetadata); align ranges to the resource size. |
-32008 | Content held elsewhere — redirect — this node does not hold the requested content, but it located peers that DO. Not a not-found: error.data.redirect names the holder(s) (providers[] = peer_id + candidate addresses), the content requested, and the redirect budget (redirect_depth, max_redirects). The named candidate set is capped — a redirect never lists every holder the node knows of, only a small bounded set — so a caller should treat the list as "enough candidates to proceed," not "every holder." The node names holders but never dials or probes them itself; reaching them is the caller's own job over its own reachability ladder, IPv6-first. Returned by the node-profile content methods (dig.getContent, dig.fetchRange) on a local miss when a provider exists. | Re-request the same content against a peer in data.redirect.providers, echoing redirect_depth in your params so the hop budget stays bounded; stop when redirect_depth reaches max_redirects. If none of the named candidates are reachable from where you are, retry the original request with proxy: true to have the node fetch the bytes on your behalf instead. |
-32009 | Range metadata unrepresentable — the metadata for a byte range alone cannot fit a frame (an inclusion proof whose base64 exceeds the 4096-byte cap), so this holder has no conforming range stream for the resource and streams no frames. Returned by the node-profile dig.fetchRange. | Treat the holder as fatal for that range: fetch the range from a different holder and do not re-request it from this one. Do not count it as a transport failure — counted that way, your client retries a peer that can never succeed. |
-32010 | Upstream error — a node acting as a thin shell relayed a method it does not resolve locally to its upstream DIG RPC, and the upstream was unreachable or returned a non-JSON response. | Retry; if it persists the upstream (e.g. rpc.dig.net) may be unavailable — try another node. |
-32011 | Stage: source directory unreadable (dig.stage, local control) — the source directory could not be read. | Confirm the directory exists and is readable; re-run. |
-32012 | Stage: no files to stage — the source directory contains no files. | Point dig.stage at a directory with content. |
-32013 | Stage: content exceeds the capsule size cap — the staged content is over the size limit. | Reduce the content to within the capsule size cap. |
-32014 | Stage: compile/IO failure — building the module hit a compile or IO error. | Check the source + disk; re-run with --verbose for detail. |
-32015 | Metadata too large — a dig.getMetadata capsule's publisher metadata section is larger than the 3 MiB response ceiling. This section is returned whole (it cannot be paged like content), and its custom/links fields are publisher-controlled, so an oversized section is refused with this bounded error rather than returned as one very large response. A normal store's metadata is well within the ceiling. | Read the store's public file surface with dig.getManifest / individual files with dig.getContent instead of the whole metadata blob; if you publish, keep the metadata custom/links fields small. |
-32016 | Push pending-reassembly limit reached — cache.pushCapsule refused this window: the node's in-flight pending-reassembly bound is exceeded (a per-requestor or global concurrent-push cap, the global pending-bytes budget, or an abandoned-partial TTL). | Wait for your in-flight pushes to complete, then retry the window. |
-32020 | Onion circuit unavailable — a mode:"privacy" content read could not be served privately (no circuit could be built, or one died mid-fetch). The node fails closed rather than downgrading to a direct fetch — a silent downgrade would deanonymize the very reader who asked for privacy. | Retry (a fresh circuit may build); or explicitly choose a fast mode:"speed" fetch if you accept revealing the read. |
-32021 | Privacy requires a local node — mode:"privacy" was requested but the caller is not the node's own trusted local originator. A node will not fetch privately for a remote/anonymous caller (that would hand it the caller's identity and query). | Run a local DIG node (in-process browser node or the OS-service node on loopback) and issue the private read to it. |
-32022 | Onion hop count out of range — the requested privacy.hops (circuit length) is outside the allowed range [2, 5] (default 3). | Request a hop count within [2, 5]. |
-32030 | Unauthorized (control) — a control.* method was called without a valid local control token. Control methods are loopback-only. (These codes are -32030+ so they never collide with the onion codes above.) | Call control methods from the local machine with the node's control token. |
-32031 | Not supported (control) — a control operation this build/pin cannot perform (e.g. §21 whole-store sync with no loaded identity). | Ensure the required capability/identity is present, or use a build that supports it. |
-32032 | Control error — a control operation failed at runtime (distinct from bad input or an absent capability). | Retry; check the node's logs; report if it persists. |
-32040 | Wallet: no chain source (WALLET_NO_CHAIN_SOURCE) — one of the control.wallet.* methods (balance, coins, peak, coinById, broadcast) had no live chain source able to answer. Reported instead of a fabricated result. | Attach/allow a chain source (a synced local node or the coinset fallback), then retry. |
-32041 | Wallet: not synced (WALLET_NOT_SYNCED) — a control.wallet.* read hit a wallet that is still syncing, with no live fallback available yet. | Wait for the node to finish syncing, then retry. |
-32042 | Wallet: read failed (WALLET_READ_FAILED) — a control.wallet.* call failed at the underlying DB / chain-source layer. | Retry; check the node's logs; report if it persists. |
-32043 | Wallet: rate limited (WALLET_RATE_LIMITED) — the open coinset-fallback rate limit is exhausted (too many arbitrary-address/coin reads in a short window). | Back off and retry; the cheap local-DB fast path is never rate-limited. |
dig-store CLI (exit codes)
dig-store exits 0 on success and a distinct non-zero code per error kind, so scripts and CI can branch on the cause. Re-run with --verbose to see the full message; many errors also print a one-line fix hint.
| Exit | Code | Meaning | What to do |
|---|---|---|---|
0 | success | The command completed. | — |
1 | other | An unclassified error. | Re-run with --verbose; see the printed message. |
2 | invalid-argument | A flag or argument was invalid. | Check dig-store <command> --help. |
3 | no-store | No store found here. | Run digs init (or cd into a store's directory). |
4 | not-found | A resource/URN/root wasn't found. | Run digs log to list generations and keys. |
5 | verification-failed | Content failed cryptographic verification. | Wrong salt/key, or the data was tampered with — recheck your URN/salt. |
6 | network | A network/transport failure. | Check your connection and that the remote is reachable (digs remote list). |
7 | non-fast-forward | The remote root has advanced past yours. | Run digs pull first, then push. |
8 | unauthorized | Not authorized for this action. | Check your credentials / the store's signing key. |
9 | no-seed | No wallet seed is set up. | Run digs seed import or digs seed generate. |
10 | bad-passphrase | Wrong passphrase for the seed. | Re-run and enter the correct passphrase. |
11 | invalid-mnemonic | The mnemonic is invalid. | Check the word list and word count (12/24). |
12 | insufficient-funds | Not enough XCH or DIG to cover the spend. | Fund the printed receive address (you need the uniform capsule price in $DIG + an XCH fee per capsule), then retry. |
13 | chain | A Chia chain/coinset error. | Check your connection to coinset.org and retry. |
14 | confirm-timeout | The on-chain confirmation timed out. | The tx may still confirm — run digs anchor status. |
15 | mint-failed | Minting the store singleton failed. | Retry; if it persists, check wallet funds and coinset.org. |
16 | update-failed | Anchoring the new root failed. | Retry; if it persists, check wallet funds and coinset.org. |
DIGHUb (web app)
When a publish or account action fails, DIGHUb shows a plain-language message and a stable code you can quote in a report. The codes below are the ones you're most likely to see.
| Code | What it means | What to do |
|---|---|---|
WALLET_DECLINED | You declined the signature in your wallet. Nothing was signed or broadcast. | Not an error — re-try and approve if you meant to publish. |
DIG_INSUFFICIENT | Not enough $DIG in your wallet to cover this capsule's price. | Top up $DIG (the publish screen links where to get it), then retry. |
COIN_CONFLICT | The coin was just spent elsewhere (double-spend / mempool conflict). | Retry — DIGHUb rebuilds the spend with a fresh coin. |
REG_PENDING | Your spend is on chain and will appear shortly. | Wait a moment — do not sign or pay again. |
WALLET_SESSION | Your wallet session can't sign (expired, watch-only, or missing method). | Disconnect and reconnect your wallet; make sure Sage is up to date. |
NET_OFFLINE | You appear to be offline. | Check your connection and try again. |
NET_TIMEOUT | The request timed out or couldn't reach the network. | Try again. |
SLUG_TAKEN | That store name is already taken. | Pick a different name. |
OVER_QUOTA | You've reached the store limit for this account. | Remove an unused store or contact support. |
COIN_RESERVED | A coin is busy finishing another transaction. | Wait a moment and try again. |
UNAUTHORIZED | Your session isn't authorized for this. | Reconnect your wallet and try again. |
FORBIDDEN | You don't have permission to do this. | Use the account that owns the store. |
NOT_FOUND | The thing couldn't be found — it may have expired. | Start over and try again. |
INVALID_REQUEST | Something about the request wasn't valid. | Try again; if it persists, report it with the code. |
UNEXPECTED | An unclassified error. | Retry; if it persists, report it with the code. |
Codes are stable; messages may improve
The code is the stable identifier — quote it in a report. The wording of a message may change as the copy gets clearer.
chia:// content loader
When you open chia:// content (in the DIG Browser, or via the extension) and it can't be served, the loader is fail-closed — it never shows unverified bytes — and surfaces a stable code so an agent can branch on why. These are catalogued in error-codes.json under the dig-loader surface.
| Code | What it means | What to do |
|---|---|---|
DIG_ERR_PROOF_MISMATCH | The served ciphertext did not verify against the on-chain generation root (tamper, or the wrong root). | Refresh; if it persists the host is serving bad bytes — try another node. |
DIG_ERR_DECRYPT_TAG | The AES-256-GCM-SIV authentication tag failed — wrong key/salt or corrupted bytes. | Recheck the URN/salt you opened; the content may be private. |
DIG_ERR_NOT_FOUND | A blind miss (decoy) — there is no resource at this address under this generation. | Check the URN/path and that the capsule actually contains it. |
DIG_ERR_NETWORK | The node or CDN was unreachable, or the transport failed. | Check your connection; try again or point at another node. |
Related
- Troubleshooting — fixes for the common failures
- FAQ — frequently asked questions
- Get help — community channels and how to file a report
- dig RPC methods — where the JSON-RPC codes come from
- On-chain anchoring — funding, costs, and confirmation timeouts