---
title: Troubleshooting
description: Debug common embedded wallet integration failures such as iframe
  origin errors, stalled approval flow, malformed signing payloads, and
  transactions that never appear in explorer.
source_url:
  html: https://thru.org/docs/wallet/troubleshooting/
  md: https://thru.org/docs/wallet/troubleshooting.md
---

# Troubleshooting

Use this page when the wallet integration exists but the dApp flow is failing or stalling.

## Iframe Or Origin Errors

### Symptom

The wallet fails before any UI appears, or initialization throws an origin error.

### Likely Cause

The embedded provider only accepts trusted iframe origins:

- `https://wallet.thru.org`
- `http://localhost` during development

### What To Check

- the `iframeUrl` is an absolute URL
- the origin is `wallet.thru.org` in production
- you did not point the SDK at an arbitrary site or an app page that is not the wallet iframe

## `connect()` Never Resolves

### Symptom

The dApp waits forever or users say the wallet never finishes connecting.

### What To Check

- keep a visible “waiting for wallet approval” state while `connect()` is in flight
- make sure the iframe is actually being shown
- if you supplied metadata, make sure `appId` and `appUrl` match the dApp origin you expect
- if the wallet is locked, expect passkey unlock before approval completes

## `signTransaction()` Fails Immediately

### Symptom

The wallet rejects the request before the approval modal is useful.

### What To Check

- the wallet is already connected before you call `signTransaction()`
- the payload is a non-empty base64 string
- the bytes are either a Thru signing payload or raw transaction bytes, not JSON or hex
- if the transaction depends on signer or fee-payer identity, you called `getSigningContext()` first

## Approval Flow Stalls

### Symptom

The wallet iframe opens, but the request seems stuck.

### What To Check

- do not hide the dApp loading state as soon as the wallet iframe appears
- if the wallet is locked, the request may be waiting for passkey authentication
- a request can also stall from the user perspective if the dApp immediately tears down the component that started the flow

## The Transaction Never Appears In Explorer

### Symptom

`signTransaction()` succeeds, but there is no explorer entry.

### Likely Cause

The dApp never submitted the signed payload, or it submitted it against a different network than the explorer view you checked.

### What To Check

- the dApp called `thru.transactions.send(...)` or an equivalent submit path after signing
- the signed payload, not the unsigned payload, is what got submitted
- the explorer network matches the RPC endpoint your dApp is using
- if needed, inspect the result with [Explorer MCP](https://thru.org/docs/api-ref/explorer-mcp/overview.md)

## Built With The Wrong Fee Payer

### Symptom

The transaction signs cleanly, but execution or submission fails because the built transaction does not match the embedded signing contract.

### What To Check

- use `getSigningContext().feePayerPublicKey` when you build the transaction
- do not assume the selected managed account is also the network signer
- if the approval modal shows a different network signer than the app expected, rebuild the transaction with the returned signing context

## Reordered Bytes After Signing

### Symptom

The app signs successfully but then fails after trying to reshuffle signature bytes and transaction payload bytes before submission.

### What To Check

- `signTransaction()` now returns canonical raw transaction bytes ready for direct submission
- do not prepend, append, or reorder signature bytes yourself after the wallet returns the result
- send the returned bytes directly through `thru.transactions.send(...)`

## Parse Or Signing Errors

### Symptom

The wallet says the transaction is invalid or signing fails unexpectedly.

### What To Check

- the transaction bytes were built by `@thru/sdk` or another correct builder
- the base64 encode/decode helpers are not corrupting bytes
- the account selection and fee payer assumptions are correct before building the transaction
- the app is not treating the selected managed account as the network signer without checking `getSigningContext()`

## Useful Next Reads

- [Embedded Wallet Integration](https://thru.org/docs/wallet/embedded-wallet-integration.md)
- [Approval and Signing](https://thru.org/docs/wallet/approval-and-signing.md)
- [Explorer MCP Overview](https://thru.org/docs/api-ref/explorer-mcp/overview.md)