Troubleshoot

Start with the symptom below. Keep the wallet and its backups intact while investigating. Reinstalling, deleting caches, or rescanning repeatedly is not a general repair procedure.

Command Not Found

For a native installer-based setup, activate it in the current terminal:

source ~/.joinmarket-ng/activate.sh
jm-wallet --help

Use the matching activation file for a custom installation directory. A missing jm-tumbler or jm-orderbook-watcher can mean you installed a restricted profile. See installation profiles. Flatpak commands must run through the Flatpak CLI wrapper.

The standalone jm-ng menu now uses $HOME/.joinmarket-ng instead of assuming /home/<username>/.joinmarket-ng. This fixes macOS and custom Linux home paths; RaspiBlitz paths are unchanged. If your home is outside /home/<username> and an older menu stored wallets there, those files remain at the old location. No files are moved or merged automatically. Keep both directories and wallet backups intact while checking the paths and configuration before making changes.

Cannot Connect To Bitcoin Core

Check that the node is running, synced, and reachable at the configured RPC address. Use either cookie authentication or a username/password pair, not both. See backend setup.

RPC error -32601: Method not found on listwallets usually means wallet support is disabled. The descriptor backend needs a wallet-enabled node. bitcoin-cli listwallets should return a JSON array, not a method error. Do not expose RPC publicly to solve a connection problem.

Neutrino TLS, Authentication, Or Sync Errors

Use an https:// URL, the service's own TLS certificate, and its bearer token. A certificate or token from another instance will not authenticate this one. Check service logs for initial sync and compact-filter prefetch completion. Historical lookups need the filter bodies as well as headers. Follow Neutrino setup or credential rotation; do not disable verification.

Tor Or Directory Connection Failed

Wait for Tor to finish bootstrapping. Check the SOCKS listener; makers also need a control listener and permission to read its authentication cookie. After a group-permission change, start a new login session. See Tor setup.

A reachable Tor service does not prove a directory is online. Repeated failures against one directory can be remote; retain multiple configured directories. Do not switch production traffic to clearnet or publish Tor credentials.

Missing Balance Or Slow Sync

Check the selected wallet, network, and BIP39 passphrase first. An incorrect passphrase derives a different wallet. For Bitcoin Core, inspect scan progress:

jm-wallet info --scan-status

Use the same wallet options as on the failing command. Imported wallets can take hours to scan, and displayed balances may be incomplete until scanning finishes. Wait for an active scan instead of starting another.

If a known address or balance remains missing after sync, compare the reported time and address-index coverage with the original wallet's records. An explicit jm-wallet rescan can repair missing coverage; choose --scan-depth only when known used addresses lie beyond the scanned range. These are potentially expensive operations, not routine startup steps. See recovery and scan diagnostics.

Fidelity bonds have separate recovery requirements. A regular wallet scan does not prove all bonds were found. See bond recovery.

Cannot Enumerate Address History

listsinceblock failed; cannot enumerate address history and Could not fetch addresses with history describe the same failed wallet-history request. Newer logs include the exception class, such as ReadTimeout, even when the exception has no message. Previously persisted used-address records are retained, but history enumeration is incomplete for that run. A restored seed may lack those records; do not treat proposed deposit addresses as verified unused until recovery coverage is established.

On Core 30.2, this empty-blockhash listsinceblock call reads transactions already known to the wallet, not historical block data. Pruning alone does not explain its failure. Collect the exception class, approximate request duration, and nearby sanitized Core logs. A timeout is a possible cause, not a diagnosis from these two messages alone. Inspect jm-wallet info --scan-status with the same wallet options, and check bitcoin-cli getblockchaininfo and bitcoin-cli getchainstates locally. Wait for an active wallet scan instead of starting another. Review diagnostics before sharing; keep wallet identifiers, addresses, transactions, paths, and credentials private. Full exception tracebacks are sensitive logs.

Finishing assumeUTXO background validation does not populate missing wallet history, and a later successful history request does not prove complete seed recovery. Do not delete metadata, repeatedly reimport, or bypass scans to clear the warning. See pruning and assumeUTXO limitations for the required block availability and recovery coverage.

Insufficient Funds Or No Eligible PoDLE UTXO

A displayed balance is not necessarily spendable for the proposed CoinJoin. Check the source mixdepth, frozen coins, confirmations, amount, and fees. The taker proof needs a UTXO meeting the configured confirmation and value requirements; see config.toml.template under [taker]. Repeated authentication attempts can also use up the available proofs for a coin. Read the reported reason before retrying; do not lower proof requirements as a workaround.

CoinJoin Failed Or Stopped

First establish whether a transaction was broadcast. Check the reported transaction ID through your own backend, jm-wallet history, and the current wallet state. A terminal timeout or missing confirmation does not prove that nothing was sent. Avoid a duplicate payment.

If no transaction was broadcast, inspect the cause: insufficient eligible coins, too few offers within your fee limits, or a connection failure. Wait for new offers or fix that cause before retrying. Do not blindly increase fee limits. For a saved tumble, use the explicit resume procedure.

If a maker refuses to sign because the mining fee is too low, normal INFO logs show the proposed fee rate and the maker's required minimum in sat/vB. The maker sends that reason to the taker, which also displays it at INFO level. Review the reported minimum and your mining-fee settings before starting another round. A full-node maker also rejects a transaction when Bitcoin Core reports a foreign input as spent or absent; sensitive logs identify the outpoint. If the prevout lookup itself fails or times out, the maker warns and proceeds without the optional fee-rate check, matching the reference maker's transaction verification behavior, unless another lookup authoritatively reports a spent or absent input. A definite refusal before signing records the attempt as failed, rather than pending, on the maker and on the taker when it receives the refusal. Revealed addresses remain protected against reuse, and an honest refusal does not add the maker to the taker's ignored list.

Maker Is Online But Earns Nothing

Takers choose when to transact and which offers to use. Being connected does not guarantee selection or profit. Check that funded offers were published, your fee and size limits, and any bond status. Avoid restarting an otherwise healthy maker just because it has not been selected.

Release Verification Failed

Do not bypass signature or dependency-hash checks. A release may be incompletely published; wait and retry the saved updater. If failure persists, check the release verification guidance and report the exact error without credentials.

Report A Problem

Record the command name, expected result, actual error, installation method, network, and backend. Collect a diagnostic report:

jm-wallet debug-info

The report is designed to omit keys, addresses, balances, and transactions. Review it before sharing. Logs, screenshots, and configuration files may contain sensitive information that this command's redaction does not cover. Never send recovery words, passphrases, wallet files, RPC credentials, or Neutrino tokens. See logging settings for how verbosity and wallet diagnostic details are controlled.

Search existing issues before filing a report. For a vulnerability, use private vulnerability reporting and follow the security policy.