tgBTC Docs
  • Intro to TON Teleport BTC
  • USER GUIDES
    • Testnet in TON
    • Signet in BTC (for PC)
    • Signet in BTC (for Mobile)
    • Mint your first tgBTC
    • Burn your tgBTC for BTC
    • View transaction history
    • Common errors and solutions
    • How passwords keep you safe
  • DEVELOPMENT
    • Build first tgBTC dApp
    • tgBTC API by TONX
  • INFORMATION DESK
    • FAQ
    • Key resources
  • Whitepaper
    • Abstract
    • Declaration of Trustlessness
    • Overview
    • Key Concepts
      • Peg-in (BTC Deposit)
        • Bitcoin Simplified Payment Verification Client
        • Transaction Confirmation, Processing and tgBTC minting
      • Peg-out (tgBTC Withdraw)
        • Building of Withdrawal Transactions
        • DKG and FROST
        • Peg-out Timing and Optimizations
      • Additional Components and Security Mechanisms
        • Bitcoin Transaction Fees
        • Validator Rotation and Key Management
        • Refund Mechanism for Expired Deposits
        • Consensus-based System Updates
        • Inspectors
    • Expanding Possibilities and Value for TON
    • Conclusion
    • Papers
Powered by GitBook
On this page
  • 📖 What you will learn
  • 📚 Before we begin
  • 1. Deposit creation errors in the password tab
  • 2. Transaction ID entry errors
  • 3. Refund page errors
  • 4. Withdraw BTC page errors
  • 🎉 What’s next?
  1. USER GUIDES

Common errors and solutions

PreviousView transaction historyNextHow passwords keep you safe

Last updated 1 month ago

This article explains the various errors that users might encounter when using . We’ve gathered a complete list of error cases — from deposit creation to withdrawal — and analyzed them to help you understand what went wrong and how to fix it.

📖 What you will learn

  • how to fix deposit creation errors

  • what to do when transaction ID entry errors occur

  • how to resolve refund page issues

  • how to fix withdraw BTC page errors

📚 Before we begin

Ensure you have the necessary test environment set up:

  • Testnet wallet in TON (e.g., Tonkeeper from our )

  • Signet wallet in BTC (e.g., UniSat or Electrum from our )

This guide assumes you are familiar with the basic operation of TON Teleport.

1. Deposit creation errors in the password tab

When creating a new deposit using the password tab, several input errors might occur. Below is a summary of common password-related issues:

Scenario

User message

How to fix

Password composition issues: Using only letters / only numbers / only special characters

“Password must contain at least one letter and one number”

Make sure your password includes at least one letter and one number, for example, MyPassword123

Password length issues: Less than 8 characters or empty input

“Password must be at least 8 characters long”

Use a password with 8 or more characters, for example, SecurePass1

Password length issues: More than 32 characters

“Password must be shorter than 32 characters”

Limit your password to 32 characters or fewer, for example, MyShortPass123

Mismatched passwords: “Password” and “Confirm password” fields do not match

“Passwords do not match”

Re-enter your password carefully in both fields to ensure they match, for example, MatchMe123

Key tips for secure password:

  • Use a mix of characters: Letters, numbers, and (optionally) symbols

  • Avoid common words: Don’t use easily guessed terms like “password” or “123456”

  • Keep it memorable: But still unique — consider a short phrase or combination of words and numbers

2. Transaction ID entry errors

When initiating a deposit, the transaction ID field is critical. Here are the common scenarios and their respective error messages:

Scenario

User message

How to fix

Incorrect Transaction ID source: Input from a non-Bitcoin blockchain (e.g., TON) or wrong network (mainnet/other testnets instead of Signet)

“Your transaction was not found or has not yet been included in a Bitcoin block”

Make sure you’re using a valid Bitcoin Signet transaction ID and that you’re on the correct network (Signet)

Empty Transaction ID field: No input provided

“Transaction ID is required”

Enter the 64-character Signet Transaction ID from your Bitcoin wallet

Improper Transaction ID length: Input is shorter than 64 characters

“Transaction ID must be 64 characters long”

Double-check that your transaction ID is exactly 64 characters (no spaces or missing digits)

Mismatched transaction details: Transaction from an old bridge address or one that belongs to another TON wallet

“Your transaction was not found or was made from another TON wallet”

Ensure you’re using the correct deposit address and transaction ID for the same TON wallet

Incorrect password for refund: When entering the refund process with the wrong password

“Incorrect password”

Re-enter the exact password used when creating the deposit. If you’ve forgotten it, unfortunately it cannot be recovered

Key tips for transaction IDs:

  • Confirm the correct network: Make sure you’re on Signet for test transactions and that your Bitcoin wallet is also configured for Signet

  • Check block inclusion: If you just sent BTC, wait for at least one confirmation in the Bitcoin (Signet) blockchain before trying to process the transaction in TON Teleport

  • Validate ID length: A Bitcoin transaction ID should always be exactly 64 characters

  • Watch for typos and spacing: Copy and paste the transaction ID carefully to avoid extra spaces or missing characters

3. Refund page errors

Errors on the refund page are often related to the Bitcoin fee field. Below is a consolidated overview:

Scenario

User message

How to fix

Bitcoin fee field issues: Field left empty or fee value is below 300 satoshis

“fee should be slightly more than 300 satoshi”

Enter a fee that is above 300 satoshis but less than your total refund amount

Excessive fee input: Fee value is equal to or exceeds the refund amount

“fee must be less than amount”

Lower the fee so that it is strictly less than the refund amount

Amount too small: The refund amount is insufficient for processing

“Amount too small to process”

Increase the BTC deposit amount to cover both the fee and the minimum required refund

Network issues: A 502 network error occurs during processing

“Network error, try again later”

Wait a few minutes, then try again. If the error persists, check your network connection or try a different browser

Incorrect deposit credentials: Attempting a refund from credits associated with a different deposit

“This password is not suitable for performing a refund”

Use the exact password associated with the original deposit. If you do not have it, you will be unable to perform the refund

Your Bitcoin Address issues: Invalid or empty Bitcoin address (e.g., mainnet, TON, or field left blank)

“Invalid Bitcoin Address” / “Address is required”

Provide a valid Signet Bitcoin address. Make sure the field is not empty and that the address format matches the Signet network requirements

Key tips for refunds:

  • Use the correct deposit credentials: Make sure you enter the exact password you created when making the deposit. Refunds won’t work with different or incorrect credentials

  • Set an appropriate Bitcoin fee: Ensure your fee is slightly above 300 satoshis but remains lower than the refund amount

  • Check your Bitcoin address format: Always use a valid Signet address if you’re testing. Mainnet or TON addresses will trigger validation errors

  • Watch for network issues: If you encounter a 502 error or any temporary downtime, wait a few minutes and try again

4. Withdraw BTC page errors

The withdraw BTC page requires accurate information in three fields: Your Bitcoin address, BTC amount, and bitcoin fee. Common errors include:

Scenario

User Message

How to fix

BTC Amount issues: Field left empty

“BTC Amount is required”

Enter the desired BTC amount you wish to withdraw (e.g., 0.0001 BTC)

BTC Amount issues: Value is 0

“Amount must be greater than 0”

Use a positive amount, for example, 0.0001 BTC

Insufficient funds: BTC Amount exceeds wallet balance

“Amount exceeds balance”

Enter an amount within your available balance. Check your wallet balance before finalizing

Minimum withdrawal requirement: BTC Amount is below 0.000004 BTC (excluding fee)

“The minimum withdrawal amount must be at least 0.000004 BTC, excluding the fee”

Increase the BTC amount to meet the minimum threshold (0.000004 BTC) plus the fee

Bitcoin Address issues: Field left empty or contains an invalid address (e.g., an address from mainnet, another network, or a TON address)

“Address is required” or “Invalid Bitcoin Address”

Provide a valid Signet BTC address. Make sure the address format matches Signet requirements and that the field is not empty

Bitcoin fee issues: Fee set to 0, lower than the contract’s minimum, equal to, or greater than the BTC Amount

“The fee is too low, the minimum required fee is [current fee]” or “The minimum withdrawal amount must be at least 0.000004 BTC, excluding the fee”

Enter a fee that is above the contract’s minimum but less than the BTC amount. Check the recommended fee in the contract and adjust accordingly

Key tips for withdrawals:

  • Check your balance first: Make sure you have enough test BTC to cover both the withdrawal amount and the network fee

  • Use a valid Signet address: Double-check that your Bitcoin address is for Signet, not mainnet

  • Mind the minimum withdrawal threshold: Always meet the 0.000004 BTC minimum (excluding the fee)

  • Set a suitable fee: Keep the fee above 0 but below the withdrawal amount, and ensure it meets or exceeds the contract’s minimum requirement

🎉 What’s next?

You’ve now learned about common errors in TON Teleport and how to fix them — from making deposits to withdrawing BTC. We hope this guide helped solve your problem.

If you still have any issues, join our to get help from our support team and fellow community members.

TON Teleport
previous guide
previous guide
Community chat