VOOL Error Book#
Coverage is bounded: catalog codes have individual sections; boundary registries have a matrix. This is not universal error coverage.
Declared catalog faults, as a human-readable view of the one canonical fault catalog (core/faults/catalog.py). This document is derived from that catalog, not a second copy of it: the codes, messages and actions below are exactly what the runtime emits.
- Schema:
vool.fault.v1 - Catalog version:
1 - Catalog digest:
4f87c03f4f60d72ce1a1a81d72f122fe29fc90dceef41073250c450452900b37 - Fault count: 54
A fault's code is stable and safe to match on; each code has its own section below whose heading is the code itself — that heading is the code's stable documentation anchor (the book's URL, #, and the code with underscores as hyphens), which receipts, surfaces and bug reports may link. Searching this page for the code as written finds its section. If a code you were given does not appear below, it is not from this build: check the build identity on the receipt, then search this book or report it with the code as written.
security#
| Code | Title | Severity | Retry | What may already have happened |
|---|---|---|---|---|
confinement_refusal | Change outside the allowed scope | high | never | Nothing was sent, signed or changed |
credential_failure | Stored credential could not be read | high | never | Nothing was sent, signed or changed |
wallet_backup_unavailable | Backup already shown once | high | never | Nothing was sent, signed or changed |
wallet_caller_refused | Caller is not VOOL's own window | high | retry_after_change | Nothing was sent, signed or changed |
wallet_card_data_refused | Card data refused | high | never | Nothing was sent, signed or changed |
wallet_chain_identity_mismatch | Chain endpoint identity unproven | high | never | A request reached an external service; no payment moved |
wallet_environment_inactive | Wrong network environment | medium | retry_after_change | Nothing was sent, signed or changed |
wallet_export_pin_not_accepted | Export unlocks only by device authentication | high | retry_after_change | Nothing was sent, signed or changed |
wallet_export_refused | Private key export refused | high | never | Nothing was sent, signed or changed |
wallet_export_unavailable | Export unavailable for this wallet | high | never | Nothing was sent, signed or changed |
wallet_legacy_surface_retired | Legacy money path retired | high | never | Nothing was sent, signed or changed |
wallet_network_disabled | Network not declared for this wallet | high | never | Nothing was sent, signed or changed |
wallet_outbound_refused | Request outside approved endpoints | high | never | Nothing was sent, signed or changed |
wallet_quote_mismatch | Approval no longer matches the preview | high | never | Nothing was sent, signed or changed |
wallet_recovery_refused | Recovery proof does not fit this wallet | high | retry_after_change | Nothing was sent, signed or changed |
wallet_signature_invalid | Signature did not match the wallet's key | high | never | A request reached an external service; no payment moved |
wallet_unlock_throttled | Wallet locked after failed unlocks | high | retry_later | Nothing was sent, signed or changed |
integrity#
| Code | Title | Severity | Retry | What may already have happened |
|---|---|---|---|---|
evidence_corruption | Answer records failed a consistency check | high | never | A local record/change happened |
integrity_verification_failure | Record failed its tamper check | critical | never | A local record/change happened |
unsupported_claim | Unsupported statements withheld | medium | never | A local record/change happened |
wallet_duplicate_payment | Payment already proposed or sent | medium | never | A local record/change happened |
policy#
| Code | Title | Severity | Retry | What may already have happened |
|---|---|---|---|---|
evm_pocket_custody_unavailable | EVM keys not held on this device | low | never | Nothing was sent, signed or changed |
permission_denied | Permission denied | medium | never | Nothing was sent, signed or changed |
wallet_acknowledgement_required | Capability acknowledgement required | low | retry_after_change | Nothing was sent, signed or changed |
wallet_amount_invalid | Amount not exact for this coin | low | retry_after_change | Nothing was sent, signed or changed |
wallet_approval_rejected | Approval not accepted | medium | never | Nothing was sent, signed or changed |
wallet_confirmation_required | Typed confirmation required | low | retry_after_change | Nothing was sent, signed or changed |
wallet_credential_mismatch | Entries did not match | low | retry_after_change | Nothing was sent, signed or changed |
wallet_dependency_unavailable | EVM libraries not installed | medium | retry_after_change | Nothing was sent, signed or changed |
wallet_device_auth_denied | Device unlock declined | low | retry_after_change | Nothing was sent, signed or changed |
wallet_disabled | Wallet is switched off | low | retry_after_change | Nothing was sent, signed or changed |
wallet_insufficient_funds | Balance does not cover amount and fee | low | retry_after_change | A request reached an external service; no payment moved |
wallet_limit_exceeded | Spending limit exceeded | medium | never | Nothing was sent, signed or changed |
wallet_not_found | Wallet, proposal or destination not recognised | low | retry_after_change | Nothing was sent, signed or changed |
wallet_password_invalid | Wallet password invalid | low | retry_after_change | Nothing was sent, signed or changed |
wallet_pin_invalid | PIN invalid | low | retry_after_change | Nothing was sent, signed or changed |
wallet_quote_expired | Preview expired or was replaced | low | retry_after_change | Nothing was sent, signed or changed |
wallet_recipient_refused | Recipient cannot safely receive this | medium | retry_after_change | Nothing was sent, signed or changed |
wallet_request_ambiguous | More than one account or network fits | low | retry_after_change | Nothing was sent, signed or changed |
wallet_setup_state_invalid | Setup step does not apply now | low | retry_after_change | Nothing was sent, signed or changed |
wallet_signing_unavailable | Wallet cannot sign from here | medium | retry_after_change | Nothing was sent, signed or changed |
wallet_storage_class_refused | Key storage is memory-only | medium | retry_after_change | Nothing was sent, signed or changed |
wallet_x402_cap_exceeded | Paid resource above the automatic cap | medium | never | Nothing was sent, signed or changed |
x402_scheme_unavailable | Payment scheme unsupported | low | retry_after_change | Nothing was sent, signed or changed |
availability#
| Code | Title | Severity | Retry | What may already have happened |
|---|---|---|---|---|
provider_exhausted | Provider limit reached | medium | retry_later | A request reached an external service; no payment moved |
provider_unavailable | Provider unreachable | medium | retry_later | Nothing was sent, signed or changed |
timeout | Timed out | medium | retry_now | Outcome unknown — check state before retrying |
tool_unavailable | Tool unavailable | low | retry_after_change | Nothing was sent, signed or changed |
wallet_broadcast_failed | Payment could not be broadcast | medium | retry_later | Outcome unknown — check state before retrying |
wallet_device_auth_unavailable | Device unlock unavailable | medium | retry_after_change | Nothing was sent, signed or changed |
wallet_quote_unavailable | Balance or fee unknown | medium | retry_later | A request reached an external service; no payment moved |
wallet_simulation_failed | Payment failed simulation | medium | retry_later | A request reached an external service; no payment moved |
cancellation#
| Code | Title | Severity | Retry | What may already have happened |
|---|---|---|---|---|
cancelled | Cancelled | info | never | Outcome unknown — check state before retrying |
internal#
| Code | Title | Severity | Retry | What may already have happened |
|---|---|---|---|---|
unknown | Unexpected error | medium | never | Outcome unknown — check state before retrying |
Reference by code#
Every code, in alphabetical order. The section heading is the code's stable anchor.
cancelled#
Cancelled
- What happened: This was cancelled, so it did not finish.
- What may already have happened: Outcome unknown — check state before retrying
- What to do next: No action needed; start again if you want it done.
- Retrying: Do not send the same request again unchanged.
- Severity: info · Category: cancellation
- Owning authority:
core.remote_fetch_policy
confinement_refusal#
Change outside the allowed scope
- What happened: A file change outside the allowed scope was blocked. Nothing outside the scope was touched.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: If this change is wanted, request it explicitly so it is inside the authorized scope.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.agent_runtime.builder.app_builder
credential_failure#
Stored credential could not be read
- What happened: A stored credential could not be read. Re-enter it in settings to continue.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: The vault entry failed to decrypt; re-store the credential or check the vault key.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.credential_store
evidence_corruption#
Answer records failed a consistency check
- What happened: This answer's supporting records failed a consistency check, so treat the answer as unverified.
- What may already have happened: A local record/change happened
- What to do next: Investigate this turn's execution ledger against the runtime event stream.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: integrity · Security-relevant: yes
- Owning authority:
core.execution_truth
evm_pocket_custody_unavailable#
EVM keys not held on this device
- What happened: EVM keys cannot be held on this device: use watch-only or an external wallet signer. Nothing was created.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Register the account watch-only or connect an external EVM signer (EIP-1193); in-process EVM custody does not exist in this build.
- Retrying: Do not send the same request again unchanged.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
integrity_verification_failure#
Record failed its tamper check
- What happened: A record failed its tamper-evidence check. Nothing was silently accepted.
- What may already have happened: A local record/change happened
- What to do next: Treat the affected receipt chain as compromised; investigate before trusting its entries.
- Retrying: Do not send the same request again unchanged.
- Severity: critical · Category: integrity · Security-relevant: yes
- Owning authority:
core.contribution_proof
permission_denied#
Permission denied
- What happened: That action was not permitted, so nothing was changed.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Check the permission policy or approval settings that govern this action.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: policy · Security-relevant: yes
- Owning authority:
core.runtime_execution_tools
provider_exhausted#
Provider limit reached
- What happened: The model provider's usage limit is reached. You can try again later.
- What may already have happened: A request reached an external service; no payment moved
- What to do next: Check quota, rate limits and billing for the configured provider.
- Retrying: Retry later — the condition that stopped this clears with time.
- Severity: medium · Category: availability
- Owning authority:
core.turn_model_call_ledger
provider_unavailable#
Provider unreachable
- What happened: The model provider could not be reached. You can try again in a moment.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Check the provider's status, network reachability, and configured endpoints.
- Retrying: Retry later — the condition that stopped this clears with time.
- Severity: medium · Category: availability
- Owning authority:
core.turn_model_call_ledger
timeout#
Timed out
- What happened: This took too long and was stopped. Trying again may succeed.
- What may already have happened: Outcome unknown — check state before retrying
- What to do next: If timeouts repeat, check network latency and provider responsiveness.
- Retrying: Retrying now may work.
- Severity: medium · Category: availability
- Owning authority:
core.remote_fetch_policy
tool_unavailable#
Tool unavailable
- What happened: That tool is not available right now, so this part was not done. Enabling it is needed before you retry.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Enable the tool for this mode in settings, or choose a different approach.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: availability
- Owning authority:
core.runtime_execution_tools
unknown#
Unexpected error
- What happened: Something went wrong on this machine while handling that. You can try again.
- What may already have happened: Outcome unknown — check state before retrying
- What to do next: See the fault's redacted cause chain in diagnostics; an unknown cause is never retried blind.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: internal
- Owning authority:
core.faults.mapping
unsupported_claim#
Unsupported statements withheld
- What happened: One or more statements were not supported by the retrieved sources and were withheld.
- What may already have happened: A local record/change happened
- What to do next: No action needed -- this is the grounding gate working. Check retrieval quality if frequent.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: integrity
- Owning authority:
core.grounding_publication
wallet_acknowledgement_required#
Capability acknowledgement required
- What happened: This step needs the capability acknowledgement first, so nothing was changed. Read what the wallet says this action does, acknowledge it exactly, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: The surface shows the capability's meaning and its exact acknowledgement text; nothing generic passes in its place.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_amount_invalid#
Amount not exact for this coin
- What happened: That amount is not an exact amount this coin can hold, so nothing was proposed. Check the amount, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Send a plain decimal amount no more precise than the coin allows and within the pilot's per-transfer ceiling.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.amounts
wallet_approval_rejected#
Approval not accepted
- What happened: The approval for this payment was not accepted, so nothing was signed or sent.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Approve the exact proposal with the owner's PIN or biometric; approvals do not transfer between proposals.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: policy · Security-relevant: yes
- Owning authority:
core.wallet.lifecycle
wallet_backup_unavailable#
Backup already shown once
- What happened: This wallet's backup key was already shown once, so it cannot be shown again. If you did not save it, cancel setup and do not send funds to this address.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: A Crypto Pilot backup is released exactly once during setup; there is no second reveal and no export for pilot wallets.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.pilot_custody
wallet_broadcast_failed#
Payment could not be broadcast
- What happened: The payment could not be broadcast. Check its status before retrying.
- What may already have happened: Outcome unknown — check state before retrying
- What to do next: Check the test-network RPC and the proposal's receipt; the spend was not recorded as sent.
- Retrying: Retry later — the condition that stopped this clears with time.
- Severity: medium · Category: availability
- Owning authority:
core.wallet.lifecycle
wallet_caller_refused#
Caller is not VOOL's own window
- What happened: This wallet action can only be started from VOOL's own window on this computer, so nothing was changed, signed or sent. Open VOOL and try again there.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Drive trusted wallet doors from the served page or the native window; a page on another origin, a framed page, a text/plain form and the command-dispatch projection are refused by design.
- Retrying: Retry after making the change this entry names.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.caller_binding
wallet_card_data_refused#
Card data refused
- What happened: Card numbers and security codes are never stored here; only a provider token is accepted. Nothing was saved.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Tokenize the card with the provider and register the token reference instead.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.cards
wallet_chain_identity_mismatch#
Chain endpoint identity unproven
- What happened: The chain endpoint did not prove the identity of the network it claims to be, so nothing was signed or sent.
- What may already have happened: A request reached an external service; no payment moved
- What to do next: Check the RPC endpoint for the network; a lying chain id or genesis is refused before any payment.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.chains
wallet_confirmation_required#
Typed confirmation required
- What happened: That step needs the typed confirmation first, so nothing was changed. Confirm it, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Read the warning and type the exact confirmation phrase to proceed.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_credential_mismatch#
Entries did not match
- What happened: The two entries did not match, so nothing was created. Enter the same PIN or password twice, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: A Crypto Pilot credential is confirmed before any key material exists.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.pilot_custody
wallet_dependency_unavailable#
EVM libraries not installed
- What happened: This build cannot do EVM signing or ABI encoding: the Ethereum libraries are not installed on this machine. Nothing was signed or sent. Solana, custody and spend ceilings are unaffected; once the libraries are installed, try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Install the EVM extras (eth-abi, eth-utils, eth-account) to enable the EVM lanes; every other wallet lane works without them.
- Retrying: Retry after making the change this entry names.
- Severity: medium · Category: policy
- Owning authority:
core.wallet.evm
wallet_device_auth_denied#
Device unlock declined
- What happened: The device unlock was declined or did not recognize this wallet, so nothing was unlocked, signed or sent. Try again, or unlock with the wallet's PIN or password.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: A declined or failed device unlock counts on the unlock throttle; repeated denials lock the wallet for a while, by design.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_device_auth_unavailable#
Device unlock unavailable
- What happened: This wallet unlocks with device authentication, which is not available here, so nothing was unlocked, signed or sent. Choose a PIN or a password on this machine, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Device unlock needs Touch ID / Windows Hello / a login password the app can reach, and a wallet that is device-bound; choose a PIN or password credential instead, or enroll device recovery.
- Retrying: Retry after making the change this entry names.
- Severity: medium · Category: availability
- Owning authority:
core.wallet.custody
wallet_disabled#
Wallet is switched off
- What happened: The wallet is switched off, so no payment was proposed or sent. Enable it first, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Enable the wallet explicitly (VOOL_WALLET_ENABLED=1) only if payments are wanted on this install.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_duplicate_payment#
Payment already proposed or sent
- What happened: This payment was already proposed or sent, so it was not sent again.
- What may already have happened: A local record/change happened
- What to do next: Check the existing proposal's receipt; use a new idempotency key for a genuinely new payment.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: integrity · Security-relevant: yes
- Owning authority:
core.wallet.proposals
wallet_environment_inactive#
Wrong network environment
- What happened: That network belongs to the other network environment (Mainnet or Test networks), so nothing was created, proposed or signed. Switch in Settings, Crypto, Developer options, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Choose the network environment deliberately in Crypto settings; accounts, balances and receipts never move between environments.
- Retrying: Retry after making the change this entry names.
- Severity: medium · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.environment
wallet_export_pin_not_accepted#
Export unlocks only by device authentication
- What happened: Export never unlocks with a PIN, password or passphrase: it unlocks only with device authentication, so nothing was revealed. Remove the credential from the request and try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: The export door is deliberately device-authenticated; a credential in the request is refused before it is ever consulted.
- Retrying: Retry after making the change this entry names.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.custody
wallet_export_refused#
Private key export refused
- What happened: Private keys are never exported by this runtime. The recovery phrase is shown once at creation and nowhere else. Nothing was revealed.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Recover a VOOL Wallet from the phrase written down at creation; there is no export door to enable.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.authority
wallet_export_unavailable#
Export unavailable for this wallet
- What happened: This wallet cannot be exported from here: it is watch-only, holds no key on this machine, or is a Crypto Pilot whose backup was shown once at setup. Nothing was revealed.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Export exists only for wallet modes that hold a key on this machine; a Crypto Pilot recovers from the phrase shown at creation, never from an export.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.custody
wallet_insufficient_funds#
Balance does not cover amount and fee
- What happened: The balance does not cover the amount plus the most this network fee can be, so nothing was prepared. Lower the amount or add funds, then try again.
- What may already have happened: A request reached an external service; no payment moved
- What to do next: Spendable excludes other in-flight holds; a Solana remainder must be zero-free and at least the rent minimum in the pilot.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.quotes
wallet_legacy_surface_retired#
Legacy money path retired
- What happened: That money path is retired: every payment goes through the wallet's proposal and approval flow. Nothing was signed or sent.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Use the wallet tools (wallet.propose) or the wallet API; the legacy signer, spender and exporter no longer exist.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.authority
wallet_limit_exceeded#
Spending limit exceeded
- What happened: That payment is above a spending limit, so it was not sent.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Review the per-transaction, daily and per-destination limits before retrying.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: policy · Security-relevant: yes
- Owning authority:
core.wallet.limits
wallet_network_disabled#
Network not declared for this wallet
- What happened: That network is not one this wallet declares for this action, so nothing was created or sent.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Use one of the declared network rows; undeclared chains, aliases and look-alike names are refused by construction.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.custody
wallet_not_found#
Wallet, proposal or destination not recognised
- What happened: That wallet, proposal or destination was not recognised, so nothing was done. Check it and try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Check the wallet id, proposal id or destination address and try again.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_outbound_refused#
Request outside approved endpoints
- What happened: That request was not allowed to leave the wallet's approved endpoints, so no connection was made.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Check the declared RPC origins and payment-resource policy; private, metadata and unapproved hosts are refused.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.outbound
wallet_password_invalid#
Wallet password invalid
- What happened: The password did not meet the policy or did not unlock the wallet, so nothing was signed or changed. Check the password and try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Wallet passwords are 10-128 characters and not only digits; a wrong password leaves the sealed key untouched and counts on the unlock throttle.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_pin_invalid#
PIN invalid
- What happened: The PIN did not meet the policy or did not unlock the wallet, so nothing was signed. Check the PIN and try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Use a 6 to 12 digit PIN; a wrong PIN leaves the sealed key untouched.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.custody
wallet_quote_expired#
Preview expired or was replaced
- What happened: This transfer preview expired or was replaced, so it cannot be approved and nothing was sent. Refresh the preview, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: A quote lives for a short window and is superseded by a refresh or an environment switch; approval never carries over.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.quotes
wallet_quote_mismatch#
Approval no longer matches the preview
- What happened: The approval no longer matches the transfer that was previewed, so nothing was signed or sent. Start again from a fresh preview.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: An approval binds one quote digest; a changed account, chain, recipient, amount, environment or fee ceiling invalidates it.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.quotes
wallet_quote_unavailable#
Balance or fee unknown
- What happened: The network did not give a complete answer for this transfer's balance or fee, so no approval was prepared and nothing was sent. Try again in a moment.
- What may already have happened: A request reached an external service; no payment moved
- What to do next: Unknown chain data is never treated as zero; check the row's endpoint and its identity proof.
- Retrying: Retry later — the condition that stopped this clears with time.
- Severity: medium · Category: availability
- Owning authority:
core.wallet.quotes
wallet_recipient_refused#
Recipient cannot safely receive this
- What happened: That recipient cannot safely receive this transfer on this network, so nothing was prepared. Check the address, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Refused: a new Solana account below the rent minimum, an executable or off-curve account, a bad EIP-55 checksum, the zero address, precompiles and system contracts.
- Retrying: Retry after making the change this entry names.
- Severity: medium · Category: policy
- Owning authority:
core.wallet.quotes
wallet_recovery_refused#
Recovery proof does not fit this wallet
- What happened: That recovery proof does not fit this wallet, so nothing was changed: the saved key must be the backup VOOL showed for this exact address, in the format it was shown. Check it and try again, or use the other options.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Recovery re-seals an existing wallet only from a backup that decodes to the wallet's own key (both derivations agree), or from an enrolled device secret released by fresh user presence; a wrong or foreign key is refused before any write and counted on the recovery throttle only.
- Retrying: Retry after making the change this entry names.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.pilot_custody
wallet_request_ambiguous#
More than one account or network fits
- What happened: More than one account or network fits this transfer, so nothing was proposed. Say which account or network you mean, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: A transfer names one account on one network; the candidates are listed in the fault context.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.transfers
wallet_setup_state_invalid#
Setup step does not apply now
- What happened: That setup step does not apply to this wallet right now, so nothing changed. Check the wallet's setup status, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Setup moves generating, awaiting backup, backup revealed, ready; cancel and resume never reveal a backup twice.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.pilot_custody
wallet_signature_invalid#
Signature did not match the wallet's key
- What happened: The signature returned for this payment did not match the wallet's key, so it was not broadcast.
- What may already have happened: A request reached an external service; no payment moved
- What to do next: Check the connected signer; a mismatched signature is refused before broadcast.
- Retrying: Do not send the same request again unchanged.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.signers
wallet_signing_unavailable#
Wallet cannot sign from here
- What happened: This wallet cannot sign from here: it is watch-only or its external signer is not connected. Nothing was sent; connect a signer, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Connect the external wallet, or create a VOOL Wallet after reading its warning.
- Retrying: Retry after making the change this entry names.
- Severity: medium · Category: policy
- Owning authority:
core.wallet.signers
wallet_simulation_failed#
Payment failed simulation
- What happened: The payment did not pass simulation, so it was not sent. Check the balance and destination, then try again.
- What may already have happened: A request reached an external service; no payment moved
- What to do next: Check the balance, the destination and the test-network RPC, then propose again.
- Retrying: Retry later — the condition that stopped this clears with time.
- Severity: medium · Category: availability
- Owning authority:
core.wallet.lifecycle
wallet_storage_class_refused#
Key storage is memory-only
- What happened: This installation keeps its device key only in memory, so a wallet created here could not be opened after a restart. Nothing was created. Switch key storage to a lasting mode, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Crypto Pilot wallets are refused while VOOL_KEY_STORAGE_MODE is ephemeral; use file or keyring storage.
- Retrying: Retry after making the change this entry names.
- Severity: medium · Category: policy
- Owning authority:
core.wallet.pilot_custody
wallet_unlock_throttled#
Wallet locked after failed unlocks
- What happened: There were too many wrong PIN or password attempts, so this wallet is locked for a while and nothing was unlocked. Wait, then try again.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Failed unlocks are counted durably per wallet and for the whole app, across restarts; the lock lifts on its own after the stated wait.
- Retrying: Retry later — the condition that stopped this clears with time.
- Severity: high · Category: security · Security-relevant: yes
- Owning authority:
core.wallet.pilot_custody
wallet_x402_cap_exceeded#
Paid resource above the automatic cap
- What happened: A paid resource asked for more than the automatic payment cap, so it was not paid.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Raise VOOL_WALLET_X402_CAP_MINOR deliberately, or pay the resource by an explicit proposal.
- Retrying: Do not send the same request again unchanged.
- Severity: medium · Category: policy · Security-relevant: yes
- Owning authority:
core.wallet.x402
x402_scheme_unavailable#
Payment scheme unsupported
- What happened: This payment offer needs a scheme this wallet cannot prove end to end, so nothing was signed. Try an offer whose scheme, token and facilitator are verified for this network.
- What may already have happened: Nothing was sent, signed or changed
- What to do next: Use an offer whose scheme, token and facilitator are verified for the network; partial signing support is never improvised.
- Retrying: Retry after making the change this entry names.
- Severity: low · Category: policy
- Owning authority:
core.wallet.x402
Boundary coverage#
Every user-facing failure boundary and the code space that classifies it. A boundary keeps its OWN closed vocabulary when it predates or sits beside vool.fault.v1; what this matrix promises is that none is silently unclassified -- a boundary with no code space would have to show that here.
| Boundary | Classified by | Codes | Where it is mapped | What the user reads | Recovery | Fault records |
|---|---|---|---|---|---|---|
| startup | process exit + boot log | no supported backend found, Database healthcheck failed | build_runtime_backbone / bootstrap_storage_environment | apps/vool_cli.py:85 ('Vool could not start: {exc}') | Install a supported runtime (mlx/torch/onnxruntime) or repair the data store; the CLI names which. | own code space |
| update | core.updater.status.UpdateFault | download_failed, download_blocked, insufficient_disk_space, verification_failed, update_not_applicable, install_failed, migration_failed, health_check_failed, destructive_work_active, stale_update_cleaned_up, unexpected_failure | UpdatePhase/UpdateFault status store (update_v2/status.json under the runtime data dir) | core/updater/status.py:42-186 plain_message() + per-fault recovery() | Per-fault recovery sentences; every failure leaves the app as it was or rolls back and restarts. | own code space |
| project_workspace | workspace root_reason | project, missing_chat, deleted_chat, unbound, project_missing, unreadable | authoritative_chat_workspace (HTTP 409 + reason) | core/web/api/service.py:4399-4407; chat toast core/vool_chat_page.py:11001; core/folder_overview.py:81-92 | Bind the chat to a project folder (Projects -> New project / pick existing) or name an explicit path; pending requests wait, nothing is cancelled. | own code space |
| filesystem_tool_execution | vool.fault.v1 | permission_denied, confinement_refusal, tool_unavailable, timeout | core.faults.mapping.map_exception at the executing seam; records via record_fault | fault user_message on the execution receipt; refusal text on the turn | Permission: request the action explicitly so it is inside an authorized scope. Confinement: same. Tool unavailable: the message names the missing prerequisite. | yes |
| permissions | vool.fault.v1 | permission_denied | the permission controller's decision (scope-named, never prose) | the approval prompt, or the typed refusal on the turn | Approve the exact action, or change the governing policy; the refusal names the governing scope. | yes |
| provider_credentials | vool.fault.v1 + attempt evidence | credential_failure, provider_credential_unavailable | per-attempt evidence; local refusal vs wire attempt distinguished before wording | core/agent_runtime/memory_runtime.py:730 _provider_auth_failure_hint ('stopped before sending... nothing was charged' vs the both-facts wording) | Restore the key under Settings -> API Keys, then send again; the message never words a local refusal as a provider rejection. | yes |
| provider_network_limits | vool.fault.v1 + ProviderErrorClass | provider_unavailable, provider_exhausted, timeout, PROVIDER_RATE_LIMIT | fault_code_for_provider_error_class (typed error class, never prose) | degraded-response hints; 429 wording quotes the provider's own Retry-After when present | Retry later for limits/exhaustion; the wording never pretends a short wait fixes a quota. | yes |
| model_availability | routing block reasons | no_ranked_provider, emergency_lane_insufficient, selected_provider_excluded_before_invocation, selected_model_unavailable, explicit_heavy_lane_unavailable, think_harder_mux_winner | explicit-pin terminal _selected_model_blocked_decision (no silent substitution) | 'Selected model X could not run (reason); no other model was substituted.' | Pick an available model or repair the named gate; a pinned model is never silently answered by another. | own code space |
| price_budget_approvals | reservation denial codes | usepod_route_not_approved, usepod_route_state_unavailable, per_call_spend_cap_exceeded, per_task_spend_cap_exceeded, daily_spend_cap_exceeded, monthly_spend_cap_exceeded, daily_call_cap_exceeded, cloud_policy_unreadable, not_owner_local, reservation_unavailable, spend_cap_exceeded, wallet_payment_authority_unavailable, wallet_payment_network_unverified, MONEY_AUTHORITY_REVOKED, MONEY_AUTHORITY_EXPIRED, MONEY_AUTHORITY_EXHAUSTED | denial['reason'] set by the refusing authority, carried verbatim to the blocked-pin terminal | _selected_model_block_cause: 'running it would exceed your spend cap' -- pre-send wording, never claims the provider was contacted | Raise the cap/ceiling deliberately in Settings, approve the model's price, or pick a model inside the cap. x402 refusals name the missing payment authority or paying network; money-authority refusals name the grant state. | own code space |
| wallet_payment | vool.fault.v1 wallet family | wallet_disabled, wallet_quote_unavailable, wallet_quote_expired, wallet_quote_mismatch, wallet_insufficient_funds, wallet_limit_exceeded, wallet_duplicate_payment, wallet_broadcast_failed, wallet_approval_rejected, wallet_x402_cap_exceeded, wallet_signature_invalid, wallet_chain_identity_mismatch, wallet_password_invalid, wallet_device_auth_unavailable, wallet_device_auth_denied, wallet_export_unavailable, wallet_export_pin_not_accepted, wallet_acknowledgement_required | each wallet boundary maps its own code before any signature or send | fault user_message on the proposal/turn; every refusal states exactly what did not happen | Per-code operator action; unknown outcomes (broadcast_failed, paid-result-unknown) say how to CHECK state and never invite a blind duplicate retry. | yes |
| contacts | ContactsError.reason | name_required, contact_not_found, contact_deleted, change_stale, revision_mismatch, too_many_pending, operation_expired, operation_cancelled, authorization_required, batch_too_large, change_invalid, change_unknown, one_change_per_contact, source_unknown, operation_stale, operation_not_pending, operation_not_found, operation_changed, operation_needs_no_confirmation, operation_committed, authorization_not_for_this_change, authorization_used, authorization_expired, credential_changed | ContactsError(reason, message, status) at the store/authority seam | exc.as_dict() with HTTP status; every sentence states 'Nothing was saved/changed' where true | Re-review the changed entry, confirm with PIN in review, or re-save before the confirmation expires. | own code space |
| plugin_skill_loading | plugin storage states + typed contract violations | accessible, missing, denied, stalled, failed, contract invalid, unmet prerequisites, unavailable capabilities, disabled by operator, duplicate plugin identity | bounded storage probe + typed contract validation law (fail-soft, never a boot hang) | catalog reason strings (core/plugin_catalog.py _reason_for) + the Plugins/Skills panel with Rescan | Grant folder access / answer the consent dialog / press Rescan; every state says 'nothing was disabled or changed'. | own code space |
| attachments | AttachmentRefused.code | too_large, too_many, unsupported_type, not_text, image_unparseable, content_mismatch, symlink_refused, invalid_id, missing_session, name_rejected, empty_file, already_bound, duplicate_id, executable_masquerade, invalid_turn, not_owned, turn_bytes_exceeded, declared_type_mismatch | AttachmentRefused(code, message, http_status) at upload/queue/send seams | the attachment chip keeps the server message; limits are shown up front | Remove or shrink/retry per the chip's reason; failed chips block send so a message never silently drops a file. | own code space |
| storage | StoreVersionError.code | VOOL_E_STORE_VERSION, VOOL_E_STORE_TOO_NEW | version-stamp check at open; boot healthcheck | startup: 'Vool could not start: {exc}'; in-turn: core/error_surface.py generic redacted surface | Downgrade refusal is deliberate (open only with the binary that upgraded the store); corruption needs the backup. | own code space |
| voice | DictationUnavailable.code | empty_recording, recording_too_large, speech_toolchain_unavailable, speech_recognizer_unauthorized, speech_recognizer_unavailable, speech_recognizer_on_device_unavailable, decoder_failed, speech_probe_failed, decoder_bad_output, speech_build_failed | DictationUnavailable(code, message, remediation); local-only by design | pre-record availability probe shows message + remediation; browser fallbacks say 'Type your message instead.' | Every typed unavailability carries a remediation (install CLT, grant Speech Recognition, add a dictation language). | own code space |
| reporting | submission failure codes | draft_not_found, approval_required, consent_mismatch, outbound_scan_refused | approval-bound submission state machine (payload sha256 binding) | exact-bytes preview dialog; redaction summary chip; 'Nothing is sent yet' | Re-approve the new bytes after any edit; local export needs no consent; duplicates return the prior issue URL. | own code space |