Error Code Reference
Every failed transaction receipt carries a structured error with a stable numeric code, a machine-readable slug, and human-authored remediation hints.Error Format
When a transaction fails, the receipt includes a structured error object:{
"code": 1202,
"slug": "E1202",
"category": "validation",
"what": "PVM execution error: Invalid input",
"why": "Address argument was not exactly 20 bytes.",
"fix": "Pass a 20-byte address (bytes or hex).",
"docs_url": "https://docs.cowboy.inc/errors/E1202",
"context": {
"exception_type": "AddressError",
"traceback": "..."
}
}
| Field | Description |
|---|---|
code | Stable numeric identifier (never re-used) |
slug | Human-friendly shorthand (E + code) |
category | One of: validation, gas, storage, runtime, runner, internal, entitlement, watchtower, token, timer, commit_reveal, cbss |
what | One-line description of the error |
why | Root cause (SDK-authored if available, else Python exception message) |
fix | Actionable remediation hint |
docs_url | Link to this documentation page |
context | Additional key-value pairs (e.g., traceback, expected, actual) |
Code Ranges
The registry contains 177 codes across 12 categories:| Range | Category | Count |
|---|---|---|
| E1000–E1099 | Transaction pre-checks | 17 |
| E1100–E1199 | PVM static validation | 1 |
| E1200–E1299 | Runtime / host API | 25 |
| E1300–E1399 | Entitlements / manifest | 5 |
| E1400–E1499 | CIP-20 tokens | 17 |
| E1500–E1599 | Timers / deferred / commit-reveal | 9 |
| E1600–E1699 | Runner / consensus / job | 22 |
| E1700–E1799 | CBSS | 52 |
| E1800–E1899 | Watchtower stream access | 17 |
| E1900–E1999 | Internal / fallback | 1 |
| E2000–E2099 | CIP-9 RAS / storage volumes | 11 |
All Error Codes
E1000–E1099: Transaction pre-checks
Signature, nonce, basefee, and balance checks that run before the actor handler executes, plus CIP-15 route-manifest acceptance checks numbered in this block.| Code | Description | Category |
|---|---|---|
E1001 | Invalid transaction signature | validation |
E1002 | Nonce mismatch | validation |
E1003 | Insufficient balance for value transfer | validation |
E1004 | Insufficient balance for gas | gas |
E1005 | Out of cycles | gas |
E1006 | Out of cells | gas |
E1007 | Gas calculation overflow | gas |
E1008 | Basefee too low | gas |
E1009 | Missing required signer | validation |
E1010 | Actor account would exceed release receipt overdraft cap | validation |
E1011 | Transaction chain_id does not match this chain | validation |
E1012 | Deferred child persistence capacity exhausted | storage |
E1013 | Actor-minted JobSubmit declared … CIP-9 attachments; an actor may declare at most … | validation |
E1014 | Actor or reserved-system address used as a signer | validation |
E1015 | Deferred payer … cannot fund the child’s maximum fee: required …, available … | gas |
E1060 | Invalid routes | validation |
E1061 | Route admission cap | runner |
E1100–E1199: PVM static validation
Compile-time determinism checks enforced at actor deploy.| Code | Description | Category |
|---|---|---|
E1101 | Non-deterministic actor code | validation |
E1200–E1299: Runtime / host API
Errors during actor execution — host calls, state access, and messaging.| Code | Description | Category |
|---|---|---|
E1201 | Out of gas inside the PVM | gas |
E1202 | Invalid input to host API call | validation |
E1203 | Host lookup not found | runtime |
E1204 | Backend storage error | runtime |
E1205 | Operation forbidden | runtime |
E1206 | Unclassified PVM-internal failure | internal |
E1207 | Missing entitlement | entitlement |
E1208 | Entitlement quota exceeded | entitlement |
E1209 | Sandbox violation (forbidden syscall) | runtime |
E1210 | Generic PVM execution error | runtime |
E1211 | Caller is not authorized | validation |
E1212 | Unsupported instruction/opcode | validation |
E1213 | Input bytes failed schema validation | validation |
E1214 | Serialization failure | internal |
E1219 | Target actor is paused by the security council | runtime |
E1220 | Target actor does not exist | runtime |
E1221 | Actor already exists at target address | runtime |
E1222 | Target account does not exist | runtime |
E1223 | Account already exists at target address | runtime |
E1224 | Referenced message id does not exist | runtime |
E1225 | Duplicate message id | runtime |
E1226 | Target mailbox is full | runtime |
E1227 | Persistent store error | internal |
E1228 | Actor destination is permanently claimed by a wallet | runtime |
E1230 | A cross-actor call targeted a handler the caller is not authorized to invoke | runtime |
E1300–E1399: Entitlements / manifest
Entitlement declaration and grant errors.| Code | Description | Category |
|---|---|---|
E1302 | Invalid manifest | entitlement |
E1303 | Non-system actor declared a system-only entitlement | entitlement |
E1304 | Entitlement conflict | entitlement |
E1305 | Entitlement param invalid | entitlement |
E1306 | Actor … already holds the maximum number of entitlements; cannot grant owner funding from … | entitlement |
E1400–E1499: CIP-20 tokens
Fungible token operations — create, transfer, approve, permit, hooks.| Code | Description | Category |
|---|---|---|
E1401 | Token not found | token |
E1402 | Token already exists | token |
E1403 | Insufficient token balance | token |
E1404 | Insufficient token allowance | token |
E1405 | Token account is frozen | token |
E1406 | Not authorized for this token operation | token |
E1407 | Mint would exceed max_supply | token |
E1408 | Transfer hook rejected the transfer | token |
E1409 | Transfer hook attempted reentrancy | token |
E1410 | Transfer hook execution failed | token |
E1411 | Transfer hook exceeded gas cap | gas |
E1412 | Transfer hook exceeded cell cap | gas |
E1413 | Permit deadline has passed | token |
E1414 | Permit nonce does not match | token |
E1415 | Permit signature does not recover to the owner | token |
E1416 | Token_transfer_batch does not support hooked tokens; transfer individually | token |
E1417 | Token id format error (not a 32-byte CIP-20 token id) | token |
E1500–E1599: Timers / deferred / commit-reveal
Scheduled execution and commit-reveal protocol errors.| Code | Description | Category |
|---|---|---|
E1501 | Timer limit exceeded for actor | timer |
E1502 | Invalid deferred transaction | validation |
E1503 | Unauthorized timer mutation | timer |
E1510 | Commitment mismatch | commit_reveal |
E1511 | Commit window closed | commit_reveal |
E1512 | Reveal window not yet open | commit_reveal |
E1513 | Reveal window closed | commit_reveal |
E1514 | Runner already committed for this job | commit_reveal |
E1515 | No commitment found for this runner | commit_reveal |
E1600–E1699: Runner / consensus / job
Off-chain compute runner registration, job dispatch, and verification.| Code | Description | Category |
|---|---|---|
E1601 | Runner already registered | runner |
E1602 | Runner not found | runner |
E1603 | Insufficient stake | runner |
E1604 | Invalid job schema | validation |
E1605 | Job not found | runner |
E1606 | Runner not assigned to job | runner |
E1607 | Insufficient runners available | runner |
E1608 | No consensus reached | runner |
E1609 | Threshold not met | runner |
E1610 | Non-deterministic results | runner |
E1611 | Unsupported verification mode | runner |
E1612 | TEE required for deterministic mode | runner |
E1613 | Runner has active jobs | runner |
E1614 | Runner has active delegated stake | runner |
E1615 | Runner deregister in dispute cooldown until block | runner |
E1616 | Job already in a terminal state; settlement runs at most once | runner |
E1617 | Runner already submitted a result for this job | runner |
E1618 | TEE-required job result carries no attestation envelope (CAE) | runner |
E1619 | Measurement binding registration requires a verified chip-root proof | runner |
E1620 | Insufficient storage-capable runners | runner |
E1621 | The chain reported that the awaited job terminated without a result | runner |
E1622 | Job callback needs … CBY to resume (budget … cycles, … cells at the current basefee); … | runner |
E1700–E1799: CBSS
Cowboy Blind Secret Store — secret access, release receipts, time-lock release (CIP-24), library errors (CIP-26), and sealed-bid auctions (CIP-34).| Code | Description | Category |
|---|---|---|
E1700 | Cbss slashing evidence already consumed for this proxy and fault class | cbss |
E1701 | Cbss committee binding mismatch: new_committee does not match pending committee | cbss |
E1702 | Cbss operator-level duplication: same operator owns multiple proxies in this set | cbss |
E1706 | CBSS: no secret metadata for (account, key_hash) | cbss |
E1707 | CBSS: this secret version was deleted by the owner | cbss |
E1708 | CBSS: override version awaits FinalizeSecretVersion | cbss |
E1709 | CBSS: ACL/entitlement does not permit this (actor, runner) | cbss |
E1710 | CBSS: policy.tee_required: runner needs a valid CIP-23 attestation | cbss |
E1711 | CBSS: hit a per-account/secret/ACL limit | cbss |
E1712 | CBSS: fewer than t proxies responsive at fetch time | cbss |
E1713 | CBSS: initial DKG ceremony for this scope is still in flight | cbss |
E1714 | CBSS: SetSecret default path with no AccountReleaseKey on file | cbss |
E1715 | CBSS: claimed wrap_epoch != release_key.committee_epoch at submission | cbss |
E1716 | CBSS: wrapped_dek AAD mismatch or malformed length | cbss |
E1717 | CBSS: wrapped_dek.version is not the supported envelope tag (2) | cbss |
E1718 | CBSS: runner_request recipient != SecretVersion.recipient | cbss |
E1719 | CBSS: request_block outside the REQUEST_FRESHNESS_BLOCKS window | cbss |
E1720 | CBSS: liveness challenge past LIVENESS_CHALLENGE_MAX_AGE_BLOCKS | cbss |
E1721 | CBSS: committee_epoch_at_serve neither current nor a retained prior | cbss |
E1722 | CBSS: proxy release-key committee_epoch != body.serve_epoch; re-issue | cbss |
E1723 | CBSS: reshare outbox full; retry in the next block | cbss |
E1724 | CBSS: runner_request.runner_sig failed verification | cbss |
E1725 | CBSS: proxy_sig failed verification | cbss |
E1726 | CBSS: malformed partial or BLS pairing check failed | cbss |
E1727 | CBSS: (release_id, proxy_id) already recorded | cbss |
E1728 | CBSS: served_at_block out of [request_block, submission_block] | cbss |
E1729 | CBSS: release set already has t entries; extra receipts rejected | cbss |
E1730 | CBSS: committee_epoch_at_serve != quorum/serve epoch; single-epoch required | cbss |
E1731 | CBSS: (release_id, proxy_id) already has an open challenge | cbss |
E1732 | CBSS: challenge before MIN_CHALLENGE_DELAY_BLOCKS elapsed | cbss |
E1733 | CBSS: AES-GCM auth-tag mismatch on wrapped_dek or object | cbss |
E1734 | Invalid library name | validation |
E1735 | Library not found | runtime |
E1736 | Library cap exceeded | gas |
E1737 | Unresolved import | validation |
E1738 | Library code parse error | validation |
E1739 | CBSS: tlock tag exceeds MAX_TLOCK_TAG_BYTES | cbss |
E1740 | CBSS: tlock target_height not beyond MIN_TLOCK_LEAD_BLOCKS | cbss |
E1741 | CBSS: tlock request already registered | cbss |
E1742 | CBSS: tlock registration cap for this block reached | cbss |
E1743 | CBSS: tlock request not registered | cbss |
E1744 | CBSS: tlock not yet releasable (head < target_height) | cbss |
E1745 | CBSS: tlock partial already submitted for this proxy | cbss |
E1746 | CIP-34: auction grant expired | commit_reveal |
E1747 | CIP-34: auction grant nonce already used | commit_reveal |
E1748 | CIP-34: auction already open for this request | commit_reveal |
E1749 | CIP-34: no open auction for this request | commit_reveal |
E1750 | CIP-34: auction closed for bids (head >= reveal_height) | commit_reveal |
E1751 | CIP-34: sealed bidder is not a registered solver | runner |
E1752 | CIP-34: auction bid cap reached | commit_reveal |
E1753 | CIP-34: auction not yet revealable (head < reveal_height) | commit_reveal |
E1754 | CIP-34: tlock key not yet released for this auction | commit_reveal |
E1800–E1899: Watchtower stream access
Stream key manager and watchtower host-call errors (CIP-7), plus the synchronous token/pause host errors that share the host-code arithmetic.| Code | Description | Category |
|---|---|---|
E1800 | Not a subscriber-paid stream | watchtower |
E1801 | Invalid account key | watchtower |
E1802 | Account key limit reached | watchtower |
E1803 | Account key revoked | watchtower |
E1804 | Invalid target key epoch | watchtower |
E1805 | Acquire epoch range too large | watchtower |
E1806 | Minimum purchase epochs not met | watchtower |
E1807 | Insufficient CBY balance | watchtower |
E1808 | One or more epochs not pre-wrapped | watchtower |
E1809 | Wrapped key committee epoch mismatch | watchtower |
E1810 | Wrapped DEK AAD does not match canonical layout | watchtower |
E1811 | Committee selector is not supported for CIP-7 content keys | watchtower |
E1812 | Insufficient token balance or allowance | token |
E1813 | Token account frozen | token |
E1814 | Token supply cap exceeded | token |
E1815 | Actor paused | runtime |
E1817 | Event payload schema does not match the declared schema | runtime |
E1900–E1999: Internal / fallback
Unclassified errors — report with tx hash.| Code | Description | Category |
|---|---|---|
E1900 | Unclassified error / fallback | internal |
E2000–E2099: CIP-9 RAS / storage volumes
Named storage volume create/lookup and manifest-commit rejections (CIP-9).| Code | Description | Category |
|---|---|---|
E2000 | Volume operation rejected (E_VOLUME_NAME_DUPLICATE) | storage |
E2001 | Volume operation rejected (E_VOLUME_ESCROW_INSUFFICIENT) | storage |
E2002 | Volume operation rejected (E_VOLUME_PARAM_INVALID) | storage |
E2003 | Volume operation rejected (E_VOLUME_NOT_FOUND_FOR_OWNER) | storage |
E2004 | Manifest commit rejected (E_COMMIT_EXPIRES_EPOCH_WINDOW) | storage |
E2005 | Volume operation rejected (E_VOLUME_RELAY_FLOOR) | storage |
E2006 | Volume operation rejected (E_VOLUME_RELAY_UNKNOWN) | storage |
E2007 | Volume operation rejected (E_STORAGE_WITHDRAW_BELOW_FLOOR) | storage |
E2008 | Volume operation rejected (E_STORAGE_WITHDRAW_EXCEEDS_RESERVE) | storage |
E2009 | Volume operation rejected (E_STORAGE_AUTO_TOP_UP_INVALID) | storage |
E2010 | Volume operation rejected (E_STORAGE_GROWTH_BELOW_FLOOR) | storage |
Reading Errors
From the CLI / RPC
curl -s http://localhost:4000/v1/transactions/<TX_HASH>/receipt | jq '.status'
From a Python Actor
import pvm_host
try:
pvm_host.set_state(b"key", b"value")
except pvm_host.HostError as e:
if e.name == "missing_entitlement": # → E1207
...
elif e.name == "entitlement_quota_exceeded": # → E1208
...
else:
raise
Raising Structured Errors
Use SDK exception classes for automatic structured error population:from cowboy_sdk.errors import AddressError, CodecError
def transfer(self, payload):
if len(target) != 20:
raise AddressError(f"expected 20 bytes, got {len(target)}")
# → receipt: code=1202, slug=E1202, category=validation