CKB KeyWayDocs

Troubleshooting

Resolve common integration, browser, channel, and routing failures.

Browser requests fail with CORS

Open the KeyWay developer console and register the exact origin, including scheme and port. Confirm that the provider uses that application's public appId. This is KeyWay application configuration; no authentication-provider dashboard access is needed.

SharedArrayBuffer or WASM startup fails

Check that the page sends:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Then verify window.crossOriginIsolated === true. Browser extensions or third-party resources without compatible cross-origin resource policy headers can also break isolation.

This requirement applies only to fiberNode="browser". The hosted node, the default, does not load Fiber WebAssembly in the page.

A wallet window closes at once or never returns

The page sends Cross-Origin-Opener-Policy: same-origin (the browser node needs it), and the window belongs to another site: JoyID, an EVM wallet site, a sign-in or payment window. The browser cuts the link between the two, so the window can't send its result back and your page sees it as closed straight away. Check window.crossOriginIsolated in the console: true means this is the cause.

  • KeyWay's JoyID backups switch transport by themselves: a window on your own site that hands the result back, or a full-page redirect when the browser blocks that window. Force one with createJoyIdBackup(undefined, { transport: "window" }) or "redirect". If you pass joyIdReturnPath to the provider, that page must render KeyWayProvider.
  • For other wallets, use their redirect flow, or move that step to a page without the isolation headers, as KeyWay's rescue page does.

An active device lease is required

With a browser node, the account's Fiber lease expired or another device took it. Call start() from useFiber() again. Avoid running the same account's channels concurrently in multiple browser profiles.

Fiber wallet is bound to another device

With a browser node, another browser still holds the Fiber lease, or the previous browser did not complete an explicit logout and encrypted backup. Log out on the active device before moving the account.

A payment has no route

The public graph did not contain a route with enough outbound liquidity for the requested amount.

  • Try a smaller payment.
  • Confirm both sender and receiver have ready public channels.
  • Allow a newly opened channel time to propagate through gossip.
  • Keep browser nodes online while testing; hosted nodes stay online after logout.
  • Check the route first with estimatePayment(), which returns a typed error such as NO_ROUTE or INSUFFICIENT_ROUTE_LIQUIDITY.

CKB balance updates slowly

CKB does not store an account balance field. The SDK asks an indexer to sum live cells for the account's lock script. Faucet and newly mined cells may appear after an indexing delay.

Opening a channel takes time

Opening a channel includes peer connection, collaborative funding construction, user approval, Lit authorization, CKB transaction broadcast, and on-chain confirmation. Use the progress callback to show the current stage rather than presenting one indefinite loading state.

await fiber.openChannel({ fundingAmount }, (stage) => {
  console.log(stage); // connecting, negotiating, confirming, signing, broadcasting, waiting
});

isn't available through KeyWay or UNSUPPORTED_METHOD

The Fiber method is blocked or isn't in KeyWay's method table, or a parameter isn't one Fiber documents for that method. See Fiber node for the allowed methods and parameters.

was not approved

The user, or your app's approval prop, declined the action: a transaction, message, channel open or close, peer change, channel settings change or payment. Nothing was signed or sent.

Email confirmation was cancelled

The action reached the user's daily confirmation amount and the user closed the code prompt. Ask them to try again and enter the code from their inbox.

Funds from a force-closed channel haven't arrived

A force close settles on-chain after about 4 hours. KeyWay then moves the settlement to the user's address: a browser node does this when it starts and every 10 minutes while it runs, and a hosted node the next time the user uses Fiber. Start the node, wait, and check the balance again. See Closing channels.

Supported scope

The current package supports CKB testnet, Fiber channels and payments in CKB and tokens (xUDT, including RUSD), invoices including hold invoices, keysend, routed payments, the CCC signer, and encrypted state handoff after explicit logout. Mainnet, backups of browser nodes after an unexpected close, and self-hosted KeyWay infrastructure are not supported.

On this page