> For the complete documentation index, see [llms.txt](https://tgbtc.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tgbtc.gitbook.io/docs/user-guides/common-errors-and-solutions.md).

# Common errors and solutions

This article explains the various errors that users might encounter when using [**TON Teleport**](https://sandbox.teleport.tg/app/auth). 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 [**previous guide**](https://tgbtc.gitbook.io/docs/getting-started/testnet-in-ton))
* Signet wallet in BTC (e.g., UniSat or Electrum from our [**previous guide**](https://tgbtc.gitbook.io/docs/getting-started/signet-in-btc-for-mobile))

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                                                                                                | <p><br></p><p>“Transaction ID is required”</p>                                   | 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                                                                             |
| **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 [**Community chat**](https://t.me/tgbtc_chat) to get help from our support team and fellow community members.
