Scoutinternal

Troubleshooting Cold, Hot, and Warm Wallet Creation, Transfers, and Access Issues

Troubleshooting Cold, Hot, and Warm Wallet Creation, Transfers, and Access Issues

Problem

Customers encounter a range of issues when working with BitGo hot, warm, and cold wallets. Common problems include: inability to create new hot wallets (e.g., backup key partner selection failing with a bad gateway error), wallet deposit addresses not loading in the UI, errors when attempting transfers from hot or cold wallets (such as "note must be a string" or transaction validity window errors), confusion about wallet passwords when sending to cold storage, and funds not being immediately available for withdrawal after trading due to settlement delays. These issues span multiple coins and chains including BTC, ETH, AVAXC, and Stellar-based assets like SOMI.

Diagnostics

  • Identify the wallet type: Confirm whether the customer is using a self-custody hot wallet, self-custody cold wallet, or custodial (cold) wallet. The wallet type dictates the signing flow and available UI options.
  • Check wallet details in admin tools: Look up the wallet ID to confirm the coin, label, enterprise, base address, balance, number of receive addresses, and user permissions.
  • Review receive address count: For wallets where the deposit address is not loading, check if the wallet has an unusually high number of receive addresses (e.g., 22,000+), which can cause UI display issues.
  • Check enterprise cold wallet enablement: Verify whether cold wallets are enabled for the customer's enterprise in production. If not enabled, the customer will not be able to create cold wallets via the API or UI.
  • Inspect the error code or error message: Collect any error IDs (e.g., cma2bsj3c0jre0e3z07bgcngd, cmdjevr3l05rl0exk06jwgc2r), HTTP errors (e.g., bad gateway / 502), or UI error strings (e.g., "note must be a string").
  • Check for known platform bugs: Search the internal Jira (e.g., WP-822) for open issues matching the customer's symptoms — particularly for backup key partner selection failures or transaction builder errors.
  • Verify settlement status for Go Account withdrawals: If the customer recently traded on a Go Account and cannot withdraw, check whether funds have settled. Settlement occurs once a day, Monday–Friday; orders completed before 9 AM PT settle the same day, and orders after 9 AM PT settle the next business day.
  • Confirm user permissions and wallet password: For cold wallet withdrawal issues, verify whether the user has the correct role (admin, spender) and understands the distinction between the login password and the wallet password/passphrase.
  • Review transaction failure logs: For failed sends, inspect the transaction JSON for missing fields (e.g., validity window) or broadcast errors (e.g., "Transaction missed its validity window").
  • Check video ID verification status: For custody or Go Account wallets, confirm whether the customer has completed video verification and is approved on the enterprise.

Resolution

Scenario: cold-hot-wallet-wallets#deposit-address-not-loading

Trigger: Customer clicks the Deposit button on a hot wallet in the UI and the address never loads — the page hangs indefinitely.

Signals: deposit address not loading, hanging, receive address, AVAXC, 22k addresses, UI timeout

Steps:

  1. Look up the wallet ID in admin tools and check the total number of receive addresses on the wallet.
  2. If the wallet has an extremely large number of receive addresses (e.g., 22,000+), this may cause the UI to hang when trying to display the deposit address.
  3. Confirm with the customer whether they are using the Deposit button next to the asset in the wallet (not the +New Transaction button at the top of the screen).
  4. Escalate to the Engineering team with the wallet ID, coin type, and the number of receive addresses, noting the UI display issue.
  5. Monitor for engineering resolution and keep the customer updated.

Notes: This has been observed on AVAXC wallets with 22,000+ receive addresses. The base address and fee address may still be queryable via API even when the UI is unresponsive. Webhook delays for forwarder address deployment (e.g., 2-day delays) may also accompany this issue.

"it appears there are 22k + receive addresses on this wallet which may be complicating this information being displayed in the UI" (ticket #108375)

"Are you using the Deposit button next to the asset in the wallet or are you using the +New Transaction button at the top of the screen?" (ticket #108375)

Scenario: cold-hot-wallet-wallets#backup-key-partner-failure

Trigger: Customer cannot select the backup key partner when creating a new hot wallet; the UI shows a bad gateway or similar error.

Signals: backup key, bad gateway, 502, hot wallet creation, WP-822, new hot wallet, ETH, BTC

Steps:

  1. Ask the customer to open the browser developer tools (F12 → Network tab) and reproduce the error to capture the specific network response.
  2. Attempt to reproduce the issue internally by creating a test hot wallet and selecting the backup key partner option.
  3. If the issue is reproducible, file or reference the existing Jira ticket (e.g., WP-822) and escalate to the Engineering team.
  4. As a workaround, advise the customer that they can proceed by storing the backup key themselves during wallet creation, rather than using the backup key partner.
  5. Once Engineering confirms the fix, notify the customer that the backup key partner option is available again.

Notes: This issue was confirmed as a platform bug affecting both the classic and new UI. The customer was able to proceed by self-storing their backup key. The fix was deployed server-side by the Engineering team.

"can reproduce, adding to https://bitgoinc.atlassian.net/browse/WP-822?focusedCommentId=384581" (ticket #203779)

"FYI, we have resolved this issue now as well and you should be able to choose our backup key partner going forward." (ticket #203779)

Scenario: cold-hot-wallet-wallets#cold-wallet-not-enabled

Trigger: Customer tries to create a cold wallet via the API (e.g., /api/v2/{coin}/wallet/generate) but the operation fails or the option is not available.

Signals: cold wallet, create, API, wallet/generate, not enabled, enterprise, testnet, production

Steps:

  1. Ask the customer whether they are working in testnet or production.
  2. Check the customer's enterprise configuration in admin tools to confirm whether cold wallets are enabled for their enterprise in the target environment.
  3. If cold wallets are not enabled, inform the customer: "Cold wallets are not enabled for your current enterprise, thus you won't be able to create cold wallets."
  4. If the customer requires cold wallet functionality, coordinate with their Customer Success Manager to enable cold wallets on their enterprise.
  5. Remind the customer that cold wallets can also be created and viewed from the UI, similar to hot wallets, for checking balance and transaction details.

Notes: API balance responses are returned in the coin's smallest unit. For example, for ETH/GTETH the response is in Wei (1 ETH = 10^18 Wei). Customers may need guidance interpreting balanceString, confirmedBalanceString, and spendableBalanceString fields.

"in production I can see cold wallets are not enabled for your current enterprise, thus you won't be able to create cold wallets." (ticket #212886)

"The balance you receive from API is actually in the coins smallest unit. So in case of GTETH you receive the response in Wei. One ether = 1,000,000,000,000,000,000 wei (10^18)." (ticket #212886)

Scenario: cold-hot-wallet-wallets#wallet-password-confusion

Trigger: Customer receives an incorrect wallet password error when attempting to transfer assets to or from a cold wallet, often because they are entering their login password instead of their wallet password.

Signals: incorrect wallet password, wallet passphrase, login password, cold wallet transfer, Forgot Wallet Password, withdrawal error

Steps:

  1. Clarify to the customer that the login password and the wallet password can be different. Changing the login password does not change wallet passwords.
  2. Explain that the creator of the wallet must use the wallet passphrase they set during wallet creation. Any other user on the wallet should use their BitGo platform password.
  3. If the customer cannot remember their wallet password, direct them to reset it via: Wallet > Settings > Forgot Wallet Password?
  4. Once the wallet password has been reset, the customer should be able to complete the withdrawal request.

Notes: This commonly affects new customers attempting their first withdrawal from a cold or custody wallet. The wallet password is specifically the BitGo wallet password (Go Account Wallet password), not a personal external wallet password.

"Please also note that your login password can be different from your wallet password and if you had changed your login password, your wallet passwords will not change." (ticket #218038)

"Please note the creator of the wallet will need to use the wallet passphrase they set for the wallet. Any other user will use their BitGo platform password." (ticket #218038)

"You can reset your wallet password from Wallet > Settings > Forgot Wallet Password?" (ticket #218038)

Scenario: cold-hot-wallet-wallets#go-account-settlement-delay

Trigger: Customer purchased crypto in their Go Account and is unable to withdraw to a cold custody wallet; spendable balance shows as 0.

Signals: Go Account, spendable balance 0, settlement, withdrawal failed, cold custody, BTC, error code

Steps:

  1. Confirm that the customer recently traded on their Go Account and is attempting to withdraw before settlement has completed.
  2. Explain the settlement schedule: "Settlement occurs once a day, every Monday through Friday. Any order completed prior to 9am PT will be settled the same day. Any order completed after this time will be settled the next business day."
  3. Advise the customer to retry the withdrawal 24 hours from the time of the trade (accounting for the settlement window).
  4. Confirm that video verification is approved on the enterprise — this is a prerequisite for cold custody withdrawals but does not affect settlement timing.
  5. Regarding multiple custody wallets created during onboarding, confirm that the customer can use either wallet for receiving funds.

Notes: This scenario is specific to Go Account trading wallets. The whitelist configuration should also be verified — the whitelist may be on the Go Account wallet rather than the custody wallet itself.

"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 #231026)

"Settlement occurs once a day, every Monday through Friday. Any order completed prior to 9am PT will be settled the same day. Any order completed after this time will be settled the next business day." (ticket #231026)

Scenario: cold-hot-wallet-wallets#hot-wallet-transfer-error-note-string

Trigger: Customer receives a "note must be a string" error or a "Transaction missed its validity window" broadcast error when attempting to send from a hot wallet.

Signals: note must be a string, validity window, broadcast error, hot wallet, send failure, transaction builder

Steps:

  1. Ask the customer for a full-window screenshot of the Transaction Builder showing all inputs (excluding password and 2FA).
  2. Check the wallet's recent transaction history for failed sends. Inspect the transaction JSON for missing fields such as the validity window.
  3. For the "note must be a string" error, advise the customer as an interim workaround to input a basic text note in the Note field within the transaction builder and retry.
  4. Escalate to the Engineering team with the wallet ID, error ID, and transaction details.
  5. Once Engineering confirms the fix is deployed, notify the customer.
  6. If the wallet was described as a "hot wallet" but is actually configured as a self-custody cold wallet, clarify to the customer that they will need to sign the transaction offline first, then upload the signed transaction before it goes to admin approvals.

Notes: In at least one case, a wallet labeled "Hot Wallet" was actually a self-custody cold wallet, which requires offline signing. Confirm the wallet type before troubleshooting the send flow. The "note must be a string" error was resolved as a platform bug by the Engineering team.

"I am investigating further the error 'note must be a string' and will follow up as soon as possible. If your team is blocked and there is urgency in moving a transaction forward, is it possible to input a basic note in the 'Note' field within the transaction builder to see if this allows you to move forward?" (ticket #249542)

"our engineering team confirmed that's an expected screen from a self-custody cold wallet. So L3 Hot Wallet 01 is a self-custody cold wallet... The user will need to sign the transaction first, after uploading the signed transaction, then it will go to admin approvals." (ticket #249542)

Scenario: cold-hot-wallet-wallets#2fa-reset-for-cold-wallet-access

Trigger: Customer is unable to log in to create or access a custodial cold wallet because 2FA is not working (no texts, emails, or authenticator notifications received), and the account becomes frozen after failed attempts.

Signals: 2FA, frozen account, custodial cold wallet, SOMI, login, passport, reset, video verification, Calendly

Steps:

  1. Acknowledge the 2FA reset request and confirm the user's identity (check that they are the primary contact and owner on the enterprise).
  2. Schedule a video conference for identity verification using the Calendly link: https://calendly.com/bitgo-client-delivery/videoid
  3. Instruct the customer to have their government-issued photo ID ready for the call.
  4. If the customer also needs an initial video ID verification (e.g., they are a new user on the enterprise), both the initial video ID and the 2FA reset can be performed in the same call.
  5. Once 2FA is reset and the customer can log in, they can proceed with wallet creation (e.g., creating a SOMI custodial (cold) wallet) at https://app.bitgo.com.

Notes: For custodial cold wallets used for locked tokens and vesting management (locks and unlocks), the only wallet option may be custodial cold. The entity name for custody is BitGo Trust Company Inc. (not BitGo New York Trust Company, LLC).

"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 #237510)

"Perform Initial Video ID and 2FA reset in same call." (ticket #237510)

"The entity name would be BitGo Trust Company Inc." (ticket #237510)

Related

  • creating-a-wallet — Covers the wallet creation flow including key holder selection, asset selection, and wallet types (hot, cold, custody).
  • best-practices-for-security-safeguards — Guidance on reviewing wallet types, policies, whitelisting strategies, and user role management.
  • keycards-and-private-keys — Explains warm wallet vs. hot wallet distinctions and laptop/PC security best practices for wallet generation.