> For the complete documentation index, see [llms.txt](https://galactic-bridge.gitbook.io/galactic-bridge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://galactic-bridge.gitbook.io/galactic-bridge-docs/troubleshooting.md). # Troubleshooting ## Messages you may see | Message | What it means | What to do | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **This token bridges over LayerZero V1** | The token uses the older protocol. | Nothing — V1 is a different set of contracts and is not supported. | | **This contract is a LayerZero application, but not a standard OFT token** | It sends LayerZero messages but has its own bespoke interface. | Use the project's own bridge. | | **This direction is currently disabled by the token's own contract** | The contract on the source network has no `peer` configured for the destination. | Pick another destination network. Nothing on your side can change this — only the token's team can re-enable it. | | **This direction is not safe to use** | The destination contract has no `peer` for the source network. The source transaction would succeed, but delivery would fail and the tokens would be stuck in transit. | Do not look for a workaround. Use another network. | | **Bridge route not found — rare route** | The route may genuinely be unused, or the network's node could not serve the data. | Press **RETRY** first, then enter the destination contract manually. | | **Search took too long on the server** | A node did not respond in time. | Try again. If it repeats for one network, that network needs a better RPC. | | **Found a bridge transaction, but its call format is non-standard** | Neither a direct example nor `quoteSend()` worked. | The contract is non-standard and cannot be reproduced generically. | | **Too many requests** | The per-IP rate limit. | Wait a minute. When self-hosting, raise `RL_SCAN_MAX` and `RL_FIND_MAX`. | ## Why a route can disappear A token existing on two networks does not mean you can move it between them. Directions are configured per contract, and projects switch them off by clearing the `peer` setting — often after a single test transaction. LayerZero Scan will still show the old delivered message, which is why history alone is not proof that a route works today. The bridge asks the contract directly instead, so you find out before signing rather than after. See [How it works](/galactic-bridge-docs/how-it-works.md). ## The wallet window is empty `VITE_REOWN_PROJECT_ID` is missing. Set it in `.env`, regenerate `frontend/.env`, and restart the dev server — Vite reads environment variables only at startup. ## Balance shows a dash Check that the wallet is connected, that the token exists on the selected source network, and that the network's RPC is reachable. The bridge retries automatically, so a persistent dash usually means the wrong network is selected. ## The wallet asks me to sign twice That is expected for tokens moved by a separate adapter: the first transaction approves the adapter, the second performs the bridge. See [Quick start](/galactic-bridge-docs/quick-start.md). ## A token search finds nothing Work through it in this order: 1. **Is it an OFT at all?** Run the five-second check from [Supported tokens](/galactic-bridge-docs/supported-tokens.md). Most "missing" tokens are not OFTs. 2. **Can the network serve logs?** Run `node backend/tools/checkLogsRpc.js`. If the verdict for that network is negative, adapter discovery cannot work there until you add an archive node. 3. **Is the bridge transaction recent enough?** Scanning covers a wide but finite range of blocks. A token last bridged months ago may fall outside it. ## Reading the logs When self-hosting, the backend console explains each decision: | Log line | Meaning | | ---------------------------------------------- | ---------------------------------------------------------------------------- | | `resolveOft: token IS OFT` | The token is the OFT itself — the simple case. | | `resolveOft: cache hit` | Answered from cache, no scanning needed. | | `findOFT: OFT=0x... via LZ-event match` | The adapter was found by intersecting logs. | | `findOFT: ... node failing → switching to ...` | The logs node started refusing requests; the scan continued on the next one. | | `route ... confirmed via peers()` | The route was confirmed from the contract, with no history. | | `peers(...) empty on 0x...` | The direction is switched off on that contract. | | `skip tx=... — router call, not OFT` | A router transaction was ignored, as intended. | | `no LayerZero bridge tx ... in scanned range` | Nothing found — usually an RPC limitation. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://galactic-bridge.gitbook.io/galactic-bridge-docs/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.