Scoutinternal

Withdrawal Errors and Failures on BitGo Platform

Withdrawal Errors and Failures on BitGo Platform

Problem

Customers encounter various errors when attempting to withdraw funds from their BitGo wallets. Common symptoms include incorrect wallet password errors, spendable balance showing 0 despite a confirmed balance, transactions stuck in "signed" status, "keychain does not have property encryptedPrv" errors, insufficient funds errors despite adequate balances, 2FA/authentication failures during withdrawal, and chain-specific broadcast failures. These issues span multiple coins (BTC, ETH, ZEC, TRX, SOL, SUI, XRP) and affect both self-managed and custodial/trading wallets, including FTX settlement accounts.

Diagnostics

  • Identify the wallet type and coin: Determine whether this is a self-managed hot wallet, custodial wallet, trading/Go account, or FTX settlement account. The wallet type dictates which resolution path applies.
  • Check wallet balance fields: In the admin tool, compare balance, confirmedBalance, spendableBalance, and lockedBalance. A confirmed balance with 0 spendable balance points to unconsolidated funds, pending settlement, or tokens stuck on receive addresses.
  • Check the user's wallet role: Verify the user has spender or admin permissions on the specific wallet (not just Enterprise Owner). Enterprise Owner does not grant wallet spend rights.
  • Inspect wallet/enterprise policy: Look for velocity limits (per-transaction, per-hour, per-day) on both the wallet policy and the enterprise policy. A deny-type enterprise policy will block transactions without requesting approval.
  • Check the send queue: For stuck transactions, inspect the send queue state (attempted, failed, signed). Note the error field and number of attempts.
  • Review the error message: Ask the customer for the exact error text or ErrorID. Key distinguishing errors:
    • unable to decrypt keychain with the given wallet passphrase → wrong wallet password
    • keychain does not have property encryptedPrv → wallet password needs to be set/updated
    • Amount Entered Exceeds Available → funds need consolidation
    • signature error at inputs → potential backend/node issue
    • BANDWITH_ERROR or Account resource insufficient error (TRX) → insufficient TRX for fees
    • BlockhashNotFound (SOL) → Solana network congestion / broadcast issue
    • token lacks required scope wallet_spend → API token missing spend permission
  • Check for UTXO-based chains (BTC, ZEC, BCH, LTC): Review total unspent count. A high unspent count (e.g., >200) can cause the spendable balance to be less than the total balance because a single transaction can only consume a maximum of 200 unspents.
  • Check ERC-20/token flush status: For ETH-based tokens showing spendable = 0 but confirmed > 0, check whether tokens are still on receive addresses and have not been flushed to the base address.
  • Check for TRX wallet root address TRX balance: For TRX and TRC-20 withdrawals, verify the root address has sufficient TRX to cover transaction fees (at least 100–150 TRX recommended).
  • Check for settlement timing (FTX/trading wallets): FTX and trading wallet funds may not be spendable until settlement completes (typically between 12 PM EST and 3 PM EST the following business day).

Resolution

Scenario: withdraw-withdrawal-funds-employment#incorrect-wallet-password

Trigger: Customer receives an error indicating the wallet passphrase is incorrect when attempting to withdraw, often seen on FTX settlement/Go accounts.

Signals: unable to decrypt keychain with the given wallet passphrase, password error, ccm: tag, wrong password, authentication error

Steps:

  1. Confirm the customer is using their wallet password (not their login password) for the withdrawal. Note: if the customer is not the wallet creator but was added as a spender/admin, they should use their BitGo login password instead.
  2. If the customer recently reset their login password, advise that this does not update the wallet password. The wallet password must be reset separately.
  3. Instruct the customer to switch to classic view:
    • Step 1: Click on the profile icon in the top right corner.
    • Step 2: Click on Switch to classic view.
  4. Navigate to Trade > Wallet Details > Settings > Forgot Wallet Password to reset the wallet password using the wallet keycard.
  5. After resetting, retry the withdrawal with the new wallet password.

Notes: This is the most common withdrawal error for FTX settlement users. Multiple tickets confirm the same resolution pattern. If the customer does not have their keycard, a separate recovery process is required.

"The error message indicates that the wallet password used during the withdrawal request is incorrect. Please try again and make sure to use the correct wallet password. If you happened to forgot the wallet password you may goto Trade > Wallet Details > Settings > Forgot Wallet Password" (ticket #26166)

"Looks like you reset your login password lately? in that case the password for the hotwallet will not be updated. You need to reset the wallet password using the wallet keycard." (ticket #185168)

"This error usually indicates an incorrect password entered. Please note that if you are not the creator of the wallet, you should use your BitGo login password here when withdrawing. Only when wallet is created by the wallet creator should the actual wallet password be used." (ticket #189156)

Scenario: withdraw-withdrawal-funds-employment#keychain-encryptedprv-missing

Trigger: Customer receives the error "keychain does not have property encryptedPrv" when attempting to withdraw, typically on Go/trading accounts.

Signals: keychain does not have property encryptedPrv, encryptedPrv, trading wallet password

Steps:

  1. Instruct the customer to Switch to classic view first (profile icon > Switch to classic view).
  2. Navigate to the Settings tab of the Go/trading account.
  3. Select Update Wallet Password.
  4. Enter the required details:
    • Current login password
    • New wallet password
    • Confirm new wallet password
  5. Complete the upgrade.
  6. Retry the withdrawal using the newly set wallet password.

Notes: This commonly occurs on newly created FTX settlement accounts where the wallet password was never explicitly set. The classic view is required to access the Update Wallet Password option.

"If you are still seeing this error - keychain does not have property encryptedPrv , please navigate to the Settings tab of your Go account and Update your Wallet Password." (ticket #33089)

"If you are running into this (keychain does not have property encryptedPrv) error, you may need to reset the trading wallet password... Please switch to classic view first and then follow the steps suggested." (ticket #204944)

Scenario: withdraw-withdrawal-funds-employment#spendable-balance-zero-settlement-pending

Trigger: Customer's spendable balance shows 0 despite having a confirmed balance, and the account is an FTX settlement or trading wallet where funds were recently deposited or traded.

Signals: spendable balance 0, Spendable Balance remains 0 USD, settlement, funds not available, FTX, trading wallet

Steps:

  1. Confirm the wallet type is a trading/Go account or FTX settlement wallet.
  2. Advise the customer that funds are not immediately available for withdrawal after trading or distribution due to settlement processing time.
  3. Settlement typically occurs between 12 PM EST and 3 PM EST on the following business day.
  4. Ask the customer to retry the withdrawal after the settlement window has passed.
  5. If the spendable balance remains 0 after the expected settlement time, escalate to investigate the settlement status.

Notes: For FTX distributions specifically, confirm the credited date. Some distributions had specific availability dates (e.g., February 18, 2025 for one wave). Refer the customer to https://www.bitgo.com/ftx-faq for general FTX information.

"Please note that FTX funds can only be withdrawn from February 18, 2025." (ticket #204171)

"Please note that funds are not immediately available for withdrawal after trading due to settlement processing time. This ensures that all transactions are properly recorded and processed. As a result, your spendable balance may show as 0 until the funds are fully settled." (ticket #205486)

Scenario: withdraw-withdrawal-funds-employment#utxo-consolidation-needed

Trigger: Customer's total balance is significantly higher than the spendable balance on a UTXO-based coin (BTC, ZEC, BCH, LTC), and the wallet has a high number of unspents.

Signals: Amount Entered Exceeds Available, insufficient funds, available balance less than total balance, unspents, consolidation, BTC, ZEC, BCH, LTC

Steps:

  1. Check the total unspent count on the wallet in the admin tool.
  2. Explain to the customer that a transaction can only consume a maximum of 200 unspents. If the sum of the 200 highest-value unspents is not sufficient to cover the transaction amount plus fees, an "insufficient funds" error will occur.
  3. Recommend the customer consolidate unspents using the BitGo API endpoint: https://developers.bitgo.com/api/express.wallet.consolidateunspents
  4. Alternatively, the customer can send smaller transactions that consume fewer UTXOs until enough are combined.
  5. Note: consolidation is not automatic due to the multi-signature wallet architecture—BitGo does not have access to private keys.

Notes: This process requires API access and an access token with spend permissions. For very large unspent counts, UI-based consolidation may not be available.

"the spendable balance is less because you have too many unspents on the wallet... Total unspents count: 12878. A transaction can only consume a maximum of 200 unspents to build the transaction, and if the sum of your 200 highest-value unspents is not sufficient to cover the transaction amount (plus fees), you will receive an 'insufficient funds' error." (ticket #77450)

Scenario: withdraw-withdrawal-funds-employment#trx-consolidation-and-fees

Trigger: Customer cannot withdraw TRX or TRC-20 tokens, seeing "Amount Entered Exceeds Available" or BANDWITH_ERROR, because funds are on receive addresses rather than the root address, or the root address lacks TRX for fees.

Signals: TRX, trx:usdt, Amount Entered Exceeds Available, consolidate, BANDWITH_ERROR, Account resource insufficient error, Out of Energy, Tron

Steps:

  1. Explain that for TRX wallets, only funds on the root address are spendable. Funds on receive addresses must be consolidated first.
  2. For UI consolidation: Navigate to the TRX wallet, click the Consolidate button, choose the coin (TRX or trx:usdt), and enter 2FA.
  3. Note: UI consolidation is supported for wallets with up to 500 addresses. For wallets with more addresses, consolidation must be done via API: https://developers.bitgo.com/coins/TRON
  4. Ensure the root address has at least 100–150 TRX to cover consolidation and transaction fees. Each receive address being consolidated also needs approximately 100 TRX for activation/fees.
  5. For the API approach, the customer must create an access token with spend permission and call the consolidation endpoint from a user with admin/spender permission.
  6. If the customer receives token lacks required scope wallet_spend, advise them to create an access token with spend permission.

Notes: For TRC-20 tokens (e.g., trx:usdt), set the coin parameter as trx:usdt. Each address holding TRC-20 tokens also needs TRX for activation. Failed TRX withdrawals due to insufficient fees may appear as small TRX deductions in the transaction history (the consumed fee amount).

"In order to make the funds spendable you first need to consolidate... Click on the button consolidate funds, this will move your TRX from the receive addresses into the root address then you are able to spend it" (ticket #49331)

"We only support consolidation via UI up to 500 addresses. Any more than that, it needs to be done via API unfortunately." (ticket #49331)

"Looks like there is not enough TRX on the address to pay for the transaction fee. Can you please fund at least 150 TRX to the wallet address... and then try the withdrawal again?" (ticket #191016)

Scenario: withdraw-withdrawal-funds-employment#erc20-token-not-flushed

Trigger: Customer has a confirmed balance of an ERC-20 token but spendable balance is 0, because the token has not been flushed from receive addresses to the base address.

Signals: ERC-20, spendable 0, token flush, forwarder, ETH token, XSGD, receive address

Steps:

  1. In the admin tool, verify that the token balance resides on receive addresses rather than the wallet base address (spendable = 0, confirmed > 0).
  2. Attempt to flush the token using the admin tool command: bga admin forwardToken --wallet <walletId> --tokenAddress <tokenContractAddress> --addresses <receiveAddress>
  3. Confirm the flush transaction is broadcast and wait for on-chain confirmation.
  4. Once confirmed, the token balance should move to the base address and become spendable.
  5. Notify the customer that the issue has been resolved.

Notes: This may require internal agent tooling access. If the forwarder contract is not deployed for the receive address, it may need to be deployed first. This scenario applies to any ERC-20 token on Ethereum wallets.

"It appears this ERC20 token has not been flushed from the receive addresses to the base address of the wallet. We will need to perform this operation for you." (ticket #149568)

Scenario: withdraw-withdrawal-funds-employment#sol-token-insufficient-sol-for-fees

Trigger: Customer attempts to withdraw an SPL token (e.g., SOL:ARC) or a SUI-based token and receives an error because the wallet's base address has 0 spendable native coin balance to cover transaction fees.

Signals: SOL, SPL token, sol:arc, spendable balance 0 SOL, fee, base address, Solana, SUI, sui:deep, sui:suins, gas fee, 0.00 SUI

Steps:

  1. Check the wallet's spendable native coin balance on the base address (SOL for Solana wallets; SUI for SUI-based token wallets). If it shows 0.00, do not immediately advise a deposit.
  2. For SUI wallets: First verify whether there is an on-chain balance at the base address that is not being reflected in the UI. Check the on-chain balance directly via the blockchain explorer or admin tooling. If an on-chain balance exists but is not showing in the platform, resolve the balance display issue before proceeding (e.g., trigger a consolidation or escalate to engineering if the balance is genuinely not syncing).
  3. Only after confirming the on-chain balance is genuinely insufficient should the customer be advised to deposit additional native coin. For SUI, the wallet must hold at least 0.1 SUI to cover gas fees.
  4. Advise the customer to send the required native coin to the wallet's base address (root address). Provide the base address from the admin tool.
  5. Once the deposit is confirmed, the customer should be able to send the token.
  6. Recommend sending enough native coin to also cover future consolidation transactions.

Notes: For Solana, transaction fees are paid in SOL from the base address. For SUI-based tokens (SUI:DEEP, SUI:SUINS, etc.), transaction fees are paid in SUI from the base address. The confirmed native coin balance may be non-zero but reside on receive addresses, not the base address, making it non-spendable for fees. Important for SUI: If the wallet shows a 0.00 SUI spendable balance, always check the on-chain balance at the base address first — a small balance may exist on-chain but not be displayed in the UI. Fix the display/sync issue first, then advise a deposit only if the on-chain balance is genuinely below the required minimum. Also note: if a Solana transaction is in "signed" state, it means it has been broadcast to the blockchain. AVOID triggering duplicate transactions for an existing signed transaction to prevent double spends.

"We show the ARC DAF wallet has a 0.00 SOL spendable balance. The fees for transactions from these wallets are paid in SOL and come from the base address of the wallet." (ticket #199481)

"If a transaction is in signed state in the BitGo system, it means the transaction has been broadcasted to the blockchain. However, it will not be displayed on-chain till it is picked for execution from the mempool. AVOID triggering duplicate transactions for an existing signed transaction." (ticket #182665)

Scenario: withdraw-withdrawal-funds-employment#2fa-authentication-error

Trigger: Customer receives an authentication error or OTP error during withdrawal, often accompanied by an ErrorID.

Signals: authentication error, 2FA, OTP, ErrorID, 2FA code, authenticator app

Steps:

  1. Ask the customer to ensure they are entering the correct, current 2FA code from their authenticator app (not an expired code).
  2. Verify the customer is not confusing auto-filled fields (e.g., password manager filling the 2FA field with login credentials).
  3. If the 2FA code is consistently failing, offer to initiate a manual 2FA reset. Require ownership verification:
    • Date of BitGo email verification (search for "Your BitGo Email Verification" in inbox)
    • 3 transaction hashes either to or from the wallet
    • Wallet balance in cryptocurrency (provide the wallet name)
    • OR: the first 8 characters and the last 8 characters of the BitGo Public Key from the keycard (specify which wallet)
  4. Once verified against records, initiate the manual 2FA reset.

Notes: Some customers may need to be advised to also check that their device clock is synchronized, as time-based OTP codes depend on accurate system time.

"If you do not have the above information, we can also accept the First 8 characters and the Last 8 Characters of the Bitgo Public Key from your keycard. Please provide the name of the wallet the keycard info applies to." (ticket #28137)

Scenario: withdraw-withdrawal-funds-employment#velocity-policy-blocking

Trigger: Customer's withdrawal is rejected by a wallet or enterprise velocity policy (spending limit per transaction, per hour, or per day).

Signals: policy, velocity limit, spending limit, enterprise policy, denied, approval required

Steps:

  1. Review the wallet policy and enterprise policy in the admin tool. Note all active velocity limits and their thresholds.
  2. Determine if the enterprise policy is a Deny policy (blocks without requesting approval) vs. an approval-required policy.
  3. If the customer needs to modify or remove the policy, the policy must first be unlocked by BitGo Support via a video ID verification call.
  4. Schedule a video call using the Calendly link: https://calendly.com/bitgo-client-delivery/videoid
  5. During the call, verify the customer's government-issued photo ID.
  6. Unlock the policy for a specified period (e.g., 48 hours) using bga policy setmutablev2.
  7. After unlocking, the customer's team must access the policy settings and remove or modify the velocity limits themselves. BitGo only unlocks the policy; the customer removes the rules.

Notes: Enterprise policy unlock and wallet policy unlock are separate operations. Both may need to be unlocked if both contain velocity limits. The unlock is time-limited (typically 48 hours).

"Reviewing the Blockchain Intelligence Group Enterprise, I see an additional Velocity Limit in place for it's policy: 0.0001 BTC per Day. The Enterprise Policy is a Deny policy and will not request approval if violated." (ticket #202353)

"We can unlock both the wallet Policy and the Enterprise policy for you on a single call if needed. We will need to confirm the ID for both of these over video... Please use the following link to schedule a time to meet with us and verify the request: https://calendly.com/bitgo-client-delivery/videoid" (ticket #202353)

Scenario: withdraw-withdrawal-funds-employment#enterprise-owner-no-wallet-permissions

Trigger: Customer is an Enterprise Owner but receives "You need to be a spender or admin on this wallet to withdraw" when attempting to send funds.

Signals: Enterprise Owner, spender, admin, wallet permissions, cannot withdraw, role

Steps:

  1. Explain that being an Enterprise Owner does not automatically grant spend permissions on individual wallets.
  2. The customer needs to be invited to the wallet as a Spender or Admin by an existing wallet Admin.
  3. Provide the role descriptions:
    • Viewers: Can view wallets and generate receive addresses.
    • Spenders: Same as viewers, plus can spend from the wallet up to the spending limit.
    • Administrators: Can view, spend, and approve transactions exceeding policy limits.
  4. If no other admin exists on the wallet, the customer may need to have another admin remove and re-add them with the correct role.

Notes: This is a permissions issue, not a technical withdrawal failure. The Enterprise-level "all users can view wallets" setting only grants view access, not spend access.

"We are showing you are an Owner on the Enterprise, but this does not carry over any permissions for use on these wallets... You need to have a wallet Admin invite you to these wallets in order to spend." (ticket #189156)

Scenario: withdraw-withdrawal-funds-employment#transaction-stuck-signed-status

Trigger: Withdrawal transactions remain in "signed" status for an extended period and are not being broadcast or confirmed on-chain.

Signals: signed, stuck, pending, broadcast, send queue, attempted, ETH, ZEC, SOL

Steps:

  1. Check the send queue in the admin tool for the affected wallet. Note the transaction state (attempted, signed), number of attempts, and the error field.
  2. If the error indicates a broadcast failure (e.g., "Operation failed but may succeed later"), escalate to the Engineering team with the wallet ID, transaction ID, and error details.
  3. For ETH/ERC-20 transactions stuck in signed state: this may be caused by a full node indexer interruption. Engineering can investigate and push the transactions to the chain.
  4. For ZEC transactions stuck due to fee estimation issues: Engineering may need to fail the transaction so the customer can resubmit. Coordinate with the customer before failing the transaction.
  5. For Solana transactions in signed state: remind the customer that "signed" means the transaction has been broadcast to the blockchain but may not appear on-chain until picked from the mempool. Do not trigger duplicate transactions.
  6. If engineering confirms the transaction should be failed, do so and advise the customer to resubmit.

Notes: For ZEC specifically, there was a known issue with fee estimation causing transactions to get stuck. Engineering implemented a fix; if the issue recurs, the customer can try sending smaller transactions with fewer UTXOs/outputs as a workaround.

"Our engineering team has fixed the issue and all transactions should be on the chain now. The reason for the transaction getting stuck because one of our full node indexers was interrupted and missed the one transaction to broadcast which is why the rest in the queue was stuck." (ticket #43447)

"you can try to send multiple transactions that spend a smaller number of UTXOs and/or have a smaller number of outputs. If the number is too high, the transaction will once again find itself in this stuck state requiring us to again fail it." (ticket #187705)

Scenario: withdraw-withdrawal-funds-employment#ui-widget-bug-new-dashboard

Trigger: Customer reports the withdrawal UI is not functioning correctly — ERC-20 tokens do not appear in the dropdown when using "+ new transactions", or the Preview button does not respond.

Signals: new transactions, dropdown, ERC-20 not showing, preview button, UI bug, new dashboard, classic view

Steps:

  1. As a workaround, instruct the customer to navigate directly to the affected wallet in the Wallets & Connections view and use the Withdraw button next to the specific token.
  2. If the Preview button is unresponsive, ask the customer to try the classic view (profile icon > Switch to classic view) and attempt the withdrawal from there.
  3. If the issue is reproducible, ask the customer to open Developer Tools (right-click > Inspect > Console tab), reproduce the issue, and share any console errors and a .har file from the Network tab.
  4. Escalate to Engineering with the console errors and .har file for investigation.
  5. Recommend using the latest version of Google Chrome on a desktop/laptop for the best experience. Advise clearing browser cache.

Notes: Some UI bugs have been caused by Content Security Policy violations in the browser. These are platform-level issues that require Engineering fixes. The classic view may serve as a reliable fallback.

"While we fix this, you should be able to navigate to and select the affected wallets in the 'Wallets & Connections' view. From there, you can use the 'Withdraw' button next to the ERC20 token to withdraw." (ticket #47953)

Scenario: withdraw-withdrawal-funds-employment#v1-wallet-withdrawal

Trigger: Customer is trying to withdraw from a V1 wallet and receives an "invalid address" error.

Signals: V1 wallet, invalid address, v1 to v2, legacy address, tbtc

Steps:

  1. Explain that for V1 wallets, funds can only be sent to a V2 wallet receive address.
  2. The customer should create a BTC V2 wallet if they do not already have one.
  3. Generate a receive address on the V2 wallet. It is best to use a Legacy address which starts with 3.
  4. Use that Legacy address as the recipient in the V1 wallet withdrawal.
  5. Once funds arrive in the V2 wallet, they can be sent to any external address.
  6. Note: There was a known cosmetic issue displaying incorrect coin abbreviations (e.g., showing TBTC instead of BTC) on V1 wallets. If the customer sees this, it is a display bug and Engineering should be notified.

Notes: V1 wallets are legacy wallets. If the customer sees their balance under "Tbtc wallet V1" but they are on mainnet, this is likely the display bug referenced above.

"For V1 wallets, you can only send to a V2 wallet receive address. Once received there, you can send to other addresses. It is best to use a Legacy address which starts with the #3." (ticket #189164)

Scenario: withdraw-withdrawal-funds-employment#account-not-found

Trigger: Customer contacts support about withdrawal issues but BitGo cannot locate their user account.

Signals: unable to locate, no account found, not registered, wrong email

Steps:

  1. Inform the customer: "We are unable to locate your user account on our platform, please send an email from your account which is registered on BitGo."
  2. Ask the customer to provide screenshots of where they are logged in so the team can verify and advise.
  3. If the customer created a BitGo starter account instead of an FTX account, direct them to create the FTX account using the claims page: https://claims.ftx.com/welcome or the Bahamas-specific page: https://www.bitgo.com/ftx-digital/
  4. The system will automatically create a new FTX Enterprise account linked to their existing BitGo email.

Notes: This commonly occurs with FTX creditors who created a generic BitGo account rather than going through the FTX claims flow. Also applies to customers who may be using a third-party app that is not BitGo.

Scenario: withdraw-withdrawal-funds-employment#chain-specific-platform-bug

Trigger: Withdrawal fails due to a platform-side bug for a specific chain (e.g., ZEC withdrawal failures, BTC send errors), not caused by customer configuration.

Signals: engineering fix, JIRA, platform bug, ZEC, BTC, release, PR, server error

Steps:

  1. Confirm the error is not caused by customer configuration (wrong password, insufficient balance, policy, etc.).
  2. Check the BitGo status page: https://status.bitgo.com/ for any known outages or incidents.
  3. Escalate to Engineering via JIRA with the wallet ID, transaction ID/requestId, coin type, and full error response.
  4. Inform the customer that the issue has been referred to Engineering and provide updates as they become available.
  5. Once Engineering deploys a fix, ask the customer to retry the withdrawal and confirm resolution.

Notes: Sporadic withdrawal failures without a clear customer-side cause should always be escalated. Request the full API error response including the requestId to facilitate investigation. Screenshots from third-party dashboards (e.g., ATM software) are not sufficient — the BitGo API error response is needed.

"We have released a fix for this issue and you should no longer see the error. Please try again and let us know if this is not the case." (ticket #18886)

"please share the full error response with requestId (if any) if you encounter this issue again and we will check further" (ticket #68868)

Related