Skip to main content
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

​
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/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