Troubleshooting
Common errors, their codes, and how to fix them
Configuration & Network Errors
| Error Code | Cause | Fix |
|---|---|---|
CFG_MISSING_NETWORK | A write/signing operation was called without a network value. | Set network explicitly — it's never optional on psbt.*, wallet.deriveAddress/signMessage/verifySignature, or transaction.broadcast. |
BitcoinInvalidNetworkException | The network value has no matching entry under Bitcoin:Networks, or isn't one of the four recognized names. | Use mainnet, testnet, signet, or regtest, and confirm it's configured in appsettings — see Networks. |
Validation Errors
| Error Code | Cause |
|---|---|
VAL_MISSING_ADDRESS | Required address field is empty. |
VAL_MISSING_TXID | Required txid field is empty. |
VAL_MISSING_BLOCK_HASH | Required blockHash field is empty. |
VAL_INVALID_HEIGHT / VAL_INVALID_START_HEIGHT | A block height field was negative. |
VAL_MISSING_RAW_TRANSACTION_HEX | transaction/broadcast called without rawTransactionHex. |
VAL_MISSING_FROM_ADDRESS | psbt/build called without fromAddress and without an explicit utxos[] list. |
VAL_MISSING_OUTPUTS | psbt/build called with an empty outputs[]. |
VAL_MISSING_PSBT | psbtBase64 is required on this operation and was empty. |
VAL_MISSING_PSBT_LIST | psbt/combine needs at least two entries in psbtBase64List. |
VAL_MISSING_EXPECTED_OUTPUTS | psbt/sign called without expectedOutputs[] — see the fund-safety rule. |
VAL_MISSING_XPUB | wallet/deriveAddress with walletType: readOnly needs xpub. |
VAL_MISSING_MESSAGE | message is required for wallet/signMessage or verifySignature. |
VAL_MISSING_SIGNATURE | signature is required for wallet/verifySignature. |
Wallet & Signing Errors
| Error Code | Cause | Fix |
|---|---|---|
WALLET_CANNOT_SIGN | walletType was readOnly (or unset) on an operation that needs to produce a signature. | Set walletType to wif or mnemonic. |
WALLET_CREDENTIAL_NOT_FOUND | credentialID was missing, or the vault entry it references doesn't exist. | Supply a valid credentialID pointing at a WIF or mnemonic credential. |
WALLET_INVALID_KEY_MATERIAL | The resolved credential is not a valid WIF-encoded key (or valid BIP-39 mnemonic) for the requested network. | Confirm the credential's network matches your network setting — a mainnet WIF won't parse against testnet, and vice versa. |
WALLET_MESSAGE_SIGNING_UNSUPPORTED_FOR_ADDRESS_TYPE | wallet/signMessage was called with addressType: p2tr. | BIP-137 has no Taproot support — use a P2WPKH wallet for message signing. |
PSBT Pipeline Errors
| Error Code | Cause | Fix |
|---|---|---|
PSBT_OUTPUT_MISMATCH |
psbt/sign's expectedOutputs[] doesn't exactly match the PSBT's real outputs — this is the design's own highest-severity fund-safety check. |
Include every output from the corresponding psbt/build call, including the change output (changeAddress/changeSats) if one was generated. See PSBT Signing Pipeline. |
PSBT_UTXO_NO_LONGER_AVAILABLE |
An input UTXO was spent by another transaction between psbt/build and psbt/finalize (a genuine race, or an expired UTXO reservation). |
Rebuild the PSBT from fresh UTXOs via a new psbt/build call. If this happens routinely under load, increase reservationTimeoutSeconds or back UtxoReservationHelper with a distributed lock — see Configuration. |
PSBT_TAPROOT_SPIKE_PENDING |
psbt/buildTaprootScriptPathInput was called for the script-multisig-leaf case, which isn't implemented yet. |
Not fixable today — see Roadmap. Key-path Taproot (P2TR) via psbt/build/psbt/sign is unaffected. |
Esplora / Network-Level Issues
| Situation | What to check |
|---|---|
| 404 on an address/tx/block lookup | Confirm the address/txid/blockHash is correct and exists on the selected network — a mainnet address will 404 against testnet's Esplora, and vice versa. |
| 429 rate limiting | The node's EsploraRateLimitHandler retries automatically. If it persists, reduce call frequency or point EsploraApiUrl at a dedicated/self-hosted Esplora instance. |
| Unconfirmed transaction "disappears" after a while | It was likely replaced (RBF) or evicted from the mempool for low fee. Check with transaction/getStatus and re-check the source address's mempool transactions. |
| Change output missing from a rebroadcast | Verify you extracted from the finalized PSBT, not an intermediate build/sign-stage copy — psbt/extract only accepts a fully finalized PSBT. |
Still stuck? Check Roadmap for known gaps (Taproot
script-path spends, distributed UTXO locking) that may explain an edge case, or ask in
community.bizfirstai.com.