Troubleshooting

The handful of things that actually go wrong, and the quickest way out of each. Most of them are not bugs — they are the wallet being careful — so the fix is usually a single command once you know what it is telling you.

Start here, every time#

terminal

wallet --json status         # reachable? locked? which chain?
wallet --json me             # which token am I actually using?
wallet events list --limit 20

Most confusion comes from being on the wrong chain, locked, or using the wrong token. These three commands settle it.

"connection refused" / the CLI can't reach the wallet#

The daemon isn't running. If you installed a service, check it (systemctl --user status canonicalwalletd / launchctl print gui/$(id -u)/com.canonical.walletd). Otherwise start it: canonicalwalletd serve --clients-file ~/.canonical/clients.json.
The socket path differs between daemon and CLI. Pass the same --socket to both, or rely on the same environment for both.

"Wallet is locked"#

Normal — the idle timer locked the vault and wiped keys from memory. Unlock:

terminal

wallet wallet unlock

If unlock is refused because backup verification is still pending, finish it first:

terminal

wallet wallet verify-backup

Nothing works against a real network#

Check the active chain. A fresh wallet defaults to Chunknet (0x34622), which isn't a network you can transact on:

terminal

wallet chains list
wallet chains switch --chain-id 0xaa36a7    # Sepolia, for example

Operations that need a chain (review, execution, balance reads) error out when no usable chain is active.

A transaction proposal won't execute#

Ask the wallet directly:

terminal

wallet proposal why-not-executable --id <id>

Common answers and fixes:

Answer	What it means	Fix
Missing an approval	Quorum not met. The default is 2 approvals, one human.	Approve with a second principal — see first transaction. A fresh solo wallet has only one approver; register a second.
Missing the human approval	The remaining approval must come from a human_operator.	Approve with a human token, not a service/agent token.
Drift detected	The environment changed since the review froze.	wallet proposal compare-review --id <id> to see the diff; re-create the proposal if the change is legitimate.
Review blocked	The semantic review is blocked or too low-confidence for a machine.	A human must review and approve, or the transaction genuinely shouldn't go.
Capability missing	Your token can't execute.	Use a token with execute_proposal (wallet me to check).
Claimed by someone else	A workflow claim is blocking duplicate work.	release-claim or handoff.

The most common surprise for new users is the first row: the wallet is multisig by default, so a single approval is never enough.

"governance_required" from a direct command#

Your policy governs that action, so the direct path is disabled. Use the proposal form instead (for example proposal add-chain instead of chains add) and take it through the quorum. Don't try to guess which path is legal — the daemon tells you.

Review timed out or came back degraded#

Reviews depend on RPC. If the provider was slow or down, the review lands degraded (machine approval blocked; a human approving a critical degraded review must supply a rationale). Once RPC is healthy:

terminal

wallet proposal resimulate --id <id>

"Did my mutating command actually apply?"#

If a command timed out mid-flight, don't blind-retry. Either check events list for your request, or re-issue the identical command with the same --idempotency-key — the wallet collapses duplicates into a single effect.

The daemon restarted — did I lose anything?#

Durable state survives: wallet, proposals, collected approvals, audit log, client registrations, policy.
The unlocked session does not: unlock again.
Approvals gathered before the restart are still valid; a half-finished proposal picks up where it left off.

A *.corrupt-<timestamp> file appeared#

The daemon quarantined a file that failed integrity checks and fell back safely:

state.corrupt-* → started from empty state (client/chain/proposal/policy records may be lost).
vault.corrupt-* → unlock/signing blocked until restored.
audit.corrupt-* → a new empty audit log started; old records remain in the quarantined file.

Prefer restoring the whole data directory from a known-good backup over continuing on the fallback. Inspect the quarantined file to understand whether it was a partial write, a manual edit, or disk corruption.

Something looks like an intrusion, not a bug#

If activity looks unauthorized rather than merely broken: lock the wallet (wallet wallet lock), revoke suspect tokens (client revoke --id ...), and read the audit log before doing anything else. Then follow your incident process.