Troubleshooting

Start with the visible symptom. Identify the responsible component or boundary. Inspect its state and error codes before choosing a supported recovery action. Do not retry operations while their broadcast state is uncertain.

Wallet surface does not load

Boundary: application-to-wallet iframe. Check the configured wallet origin, service route, CSP frame-src, frame-ancestor policy, asset content types, and browser console origin errors. Correct the deployment or origin allowlist. Then reload the wallet UI.

An older client receives an upgrade-required response

Boundary: SDK, hosted wallet assets, and backend release identity. The backend rejects unsupported wallet-management protocols with HTTP 409 and an upgrade message. Display it and reload the matching application and wallet assets. Stop automatic retries of the same incompatible request. Follow the deployment requirements. The application and wallet host must also agree on iframe protocol 23.0.0.

Registration signs but is absent from Console

Boundary: Gateway completion publication. Registration can commit locally before the directory acknowledges it. Check pending publication rows, scheduled handler execution, directory access, and migration 0081. Retry the recorded publication through the scheduled handler. Do not create another wallet. Region moves remain unavailable until acknowledgment.

Sign-in downloads start after a click

Boundary: lazy wallet runtime. When no wallet is stored, connection alone does not load the sign-in runtime. Attach authMenu.prepare() to pointer, focus, or touch intent, or mount HostedSeamsAuthMenu earlier. This downloads code without reserving a wallet or requesting a credential.

Initial tenant authorization expired

Boundary: custody creation journal. An unused authorization can be renewed only after the Router persists its fence. A started ceremony must recover with its exact original authorization. Check Wallet Runtime's control relay and coordinated backend versions before retrying. Do not substitute a new grant for an operation that already started.

A regional wallet cannot be routed

Boundary: wallet-home directory and regional bindings. Check the wallet's recorded home and the serving Worker/D1 binding evidence. A directory outage requires restoring directory access and retrying the same operation safely. Wrong-home rejection requires correcting routing. Never write to a fallback region or assign an existing wallet a new home to bypass the failure.

Passkey prompt is unavailable

Boundary: browser capability, RP ID, and wallet origin. Inspect the public capability-selection result, secure-context status, iframe permissions, and RP scope. Offer a supported auth method or correct the origin configuration. Do not loop the credential prompt.

Registration succeeded but a signer is not ready

Boundary: provisioning lifecycle. Inspect the successful RegistrationResult branch and current provisioning state. Wait for a pending state, retry only a retryable failure, and continue after the exact capability is ready.

Signing reports a session or subject mismatch

Boundary: wallet-session identity. Confirm that the wallet-session reference, account or chain target, wallet ID, network, and current SDK client all describe the same wallet lifecycle. Re-authenticate and rebuild exact references from validated state.

Transaction status is uncertain

Boundary: broadcast and chain finality. Use the operation hash or request ID to query the configured network and reconcile nonce-lane state. Retry only after proving the previous transaction was not accepted.

Appearance differs between app and wallet

Boundary: rendering origin. Confirm that app-owned components receive the React Theme tokens and wallet-owned surfaces receive matching SDK appearance tokens for the active mode. Verify contrast after correcting both channels.

Tenant-root refresh is throttled or already running

Boundary: tenant-root operation admission. In releases containing R120's hourly gate, HTTP 429 with tenant_root_refresh_throttled returns retryAtMs and Retry-After. Wait until that server-computed time before starting a new manual refresh. HTTP 409 with tenant_root_refresh_in_progress identifies a different operation already in progress. Preserve the original operationId when retrying an interrupted request. Generating new IDs cannot resume it.

Verify the release and policy of the actual environment. The implemented contract alone does not establish deployment configuration.

Tenant-root backup cannot be opened

Boundary: role-local backup provider. Check the affected role's KMS key reference, enabled key version, service-account access, and retained R2 object against the authoritative activation evidence. Keep credentials and decrypted material out of logs. Restore access to the recorded key version. A replacement key cannot decrypt ciphertext written under the lost version.

A complete database-loss incident also requires authoritative identity and activation records. Follow tenant-root backup recovery requirements.

Refresh activated but retirement is incomplete

Boundary: tenant-root lifecycle cleanup. Inspect the authoritative revision and role receipts. Resume the original operation's cleanup rather than reactivating the retired epoch or starting repeated rotations. Working signing does not prove retirement completed, and deleting active backup objects does not prove all historical ciphertext is unrecoverable.

What to collect for support

Collect release, environment, browser, operation ID, public error code, event phase/status, and redacted console or network evidence. Exclude credentials, tokens, assertions, OTPs, recovery data, and key material.

External NEAR wallets

Boundary: application document and selected external wallet. The connector is a development preview included in npm version 0.42.0. See availability and integration.

• Meteor may inject its page API after initial load. Retry after initialization in the correct browser profile. A toolbar icon alone does not prove page API readiness.
• HOT is mainnet-only in this connector. The testnet picker intentionally disables it.
• Intear needs a popup allowed for the app origin. The connector accepts only its fixed wallet origin and the exact request window.
• After disconnect, read a new connected snapshot before signing. A stale snapshot returns connection_changed.
• Preserve a returned hash and use checkOutcome for unresolved execution. For submission_unknown, check wallet activity before any new send.

An external connection does not create a Seams login. Use external connection state to enable external transaction controls.