LI.FI Widget Error Handling Guide
Handle wallet issues, route failures, and transaction-state UX with a production-minded LI.FI widget model that keeps the host product in sync with what the embedded swap or bridge flow is actually doing.
A LI.FI widget integration is not production-ready just because the widget renders and can discover routes. The harder part starts when a wallet is disconnected, a route cannot execute, a transfer stalls, or the rest of the product needs to explain what just happened.
If you still need the baseline setup, start with the LI.FI widget docs. If your main open question is route scope or wallet timing before execution begins, pair this guide with the LI.FI Widget Supported Wallets and Routing Guide. If you are already wiring host-side listeners, continue into the LI.FI Widget Event Hooks Guide.
Why LI.FI widget error handling needs its own implementation pass
A bridge or swap flow can fail for reasons that are invisible in a static UI review: no connected wallet, route mismatch, execution failure, ambiguous progress, or a host page that never reacts when the widget emits the signal users actually need.
Good error handling turns an embedded swap flow from a fragile demo into a supportable user journey. That means thinking about failure, progress, recovery, and product messaging alongside integration and routing decisions instead of after the happy path already ships.
What reliable handling usually includes
- Constrain avoidable failures early with route, chain, token, and wallet decisions.
- Observe widget lifecycle events so the host page stays aligned with execution state.
- Explain pre-execution, progress, success, and failure states clearly outside the widget.
- Offer a real next action such as retrying, reconnecting, changing route inputs, or contacting support.
The repo signals that matter for error handling
The wrapper is configuration-first
In this repo, the local LiFiWidget wrapper exposes configuration-oriented props. That matters because many avoidable failure states should be reduced through configuration first, not explained later in support copy.
- integrator
- config
- variant and subvariant
- appearance
- allowedChains
- allowedTokens
- transactionSettings
- walletManagement
- fee and feeConfig
Host-side observation belongs in the event system
The existing event hooks guide shows that host code can subscribe to widget lifecycle events. Those events are the bridge between widget state and product state, which makes them the practical foundation for progress messaging, analytics, retry UX, and support-aware recovery handling.
RouteExecutionStartedRouteExecutionUpdatedRouteExecutionCompletedRouteExecutionFailedAvailableRoutesRouteSelectedContactSupportPageEnteredWidgetExpandedSendToWalletToggled
@lifi/widget package version before publishing production-specific examples.Start by reducing the failure surface
Narrow route scope when the product expects a narrow outcome
Broad route discovery can be useful in a dedicated exploration surface, but many embedded swap and bridge flows are not truly open-ended. If the product expects one destination chain, one funding path, or one operational transfer pattern, narrower route configuration is often the simplest form of error prevention.
Keep wallet timing intentional
The wrapper supports walletManagement, including auto-connect and supported-wallet configuration shapes. Before release, test first visit, reload, reconnect, and direct entry states so users are never left guessing whether they are blocked, loading, connected, or expected to switch wallets manually.
Avoid overly optimistic transaction defaults
Settings such as slippage and gas behavior should be applied carefully and only when they improve the real flow. A conservative first release is usually easier to support than a heavily optimized one with weak status messaging.
The four LI.FI widget states your host app should always distinguish
1. Pre-execution
Users may still be connecting a wallet, selecting chains, comparing routes, or deciding whether the flow fits the rest of the product.
- explain what the widget is doing in product terms
- clarify whether wallet connection is required before the next action
- surface route constraints early when the journey is intentionally narrow
- avoid showing success-style UI before execution begins
2. In progress
Once execution starts, the host product should acknowledge that the route is actively running rather than leaving all state interpretation inside the embed.
- show a page-level progress banner or status rail when the route is part of a larger flow
- treat RouteExecutionUpdated as progress, not as final success
- keep support messaging calm and specific
- avoid telling users to restart unless failure is actually confirmed
3. Completed
Completion is the moment to unlock the next product step, confirm the operational outcome, and keep analytics aligned with what really finished.
- confirm what completed in product language
- offer the next useful action instead of stopping at a generic success message
- update dependent page state only after completion is confirmed
- keep the outcome consistent with the rest of the user journey
4. Failed
A failed route should feel explicit and recoverable where possible. The widget can emit failure, but the host page still decides what recovery looks like.
- state clearly that execution did not complete
- avoid hiding failure behind a vague loading or retry message
- suggest one likely next action: retry, reconnect, change inputs, or contact support
- preserve enough context that users do not need to start from zero when recovery is possible
Recommended host-side error handling model
The event hooks guide already demonstrates a simple local status model with values such as idle, running, completed, and failed. That is a strong starting point because it maps directly to how users experience the flow.
A dependable host-side model usually combines a local status state, a last-event marker for debugging, lightweight analytics, a visible page-level status area outside the widget, and a real support or recovery path when the route fails.
The failure categories that deserve distinct handling
Wallet connection issues
Many visible widget failures begin as wallet-state confusion. The user may be disconnected, partially connected, or unsure whether the current session is valid for the intended route.
- make the wallet requirement obvious
- clarify whether reconnection is needed
- avoid blaming the route when wallet state is the real blocker
- keep reconnect actions close to the widget surface
Route discovery problems
Sometimes the issue is not execution failure but route readiness. A user may not reach a route-ready state, may see too many choices, or may select a path that the product did not expect.
- treat AvailableRoutes and RouteSelected as useful diagnostic signals
- check whether the flow is broader than the product promise
- tighten allowedChains or allowedTokens when users repeatedly choose unhelpful paths
- explain the intended route outcome before execution starts
Execution failures
These are the most visible errors because they happen after the user commits to the route. This is where host-side copy and recovery logic matter most.
- acknowledge the failure clearly
- offer a retry path only when retry actually makes sense
- preserve route context for support or self-service recovery
- avoid a dead-end “something went wrong” message
Stalled or ambiguous progress
An embedded swap or bridge flow can look stuck even when it is still progressing, so progress handling needs its own status language instead of being lumped into success or failure.
- use RouteExecutionUpdated as a progress signal
- avoid premature failure language
- keep users informed that the route is still active
- show support options only after failure is confirmed or when the user explicitly asks for help
Support intent
The ContactSupport event is valuable because it tells the host product when the user has moved from self-service into assisted recovery.
- log support intent in analytics or internal tooling
- preserve recent route context where safe and appropriate
- connect the support action to a real destination instead of a dead-end link
- review whether repeated support intent points to a preventable product issue
A practical workflow for implementing LI.FI widget error handling
1. Prove the smallest happy path first
Render the widget in the real page container and confirm a basic route can execute before layering on host-side failure handling.
2. Add route lifecycle listeners in host code
Start with RouteExecutionStarted, RouteExecutionUpdated, RouteExecutionCompleted, and RouteExecutionFailed so the host app can observe the route lifecycle clearly.
3. Add page-level status messaging
Create short, stable copy that distinguishes pre-execution, in-progress, completed, and failed states outside the widget.
4. Review avoidable failures in configuration
Revisit route scope, wallet timing, token constraints, and transaction defaults only after the status model is working.
5. Add support-aware recovery handling
Decide whether recovery means retrying, reconnecting, changing route inputs, or escalating to support based on the surrounding product journey.
What good error copy should accomplish
Error copy in a LI.FI widget flow should do more than apologize. It should name the state clearly, separate progress from failure, give one useful next action, and match the product context around the widget instead of dumping support work onto the user.
Weak copy usually collapses everything into loading, failed, or try again later. Strong copy helps the user move.
When a LI.FI widget should retry versus when it should redirect the user
Retry is usually reasonable when
- the user is still in the correct wallet and route context
- the action is clearly repeatable from the current screen
- relevant inputs can be preserved without confusion
- the failure appears transient rather than structural
A route change is usually better when
- the current chain or token path no longer fits product constraints
- the user chose an overly broad path and needs a narrower route
- wallet state is no longer reliable
- the product needs the user to revisit an earlier step before trying again
Support escalation is usually better when
- the route repeatedly fails with no obvious self-service correction
- the product has operational constraints that users cannot fix alone
- the host page needs a human-reviewed path for completion or reconciliation
Production checklist for LI.FI widget error handling
- the host app distinguishes idle, running, completed, and failed states
- RouteExecutionUpdated is treated as progress, not as final success
- the page has clear behavior for disconnected, reconnecting, and direct-entry wallet states
- route scope reflects the actual product promise instead of exposing unnecessary choice
- allowedChains and allowedTokens are used when product constraints are real
- page-level copy explains what users should do when execution fails
- support intent has a real destination if ContactSupport is used
- analytics or internal visibility capture route start, progress, completion, and failure at a minimum
- the widget has been tested inside the production container, not only in isolation
- adjacent docs point the team to route planning, setup, and event instrumentation next steps
How this guide fits the existing LI.FI docs flow
Use this route as the operational layer between basic widget setup, route planning, and deeper host-side instrumentation.
- LI.FI Widget docs for base setup and integration framing
- LI.FI Widget Supported Wallets and Routing Guide for route scope and wallet timing decisions
- LI.FI Widget Event Hooks Guide for lifecycle subscriptions and analytics wiring
- LiFi Playground Guide for broader incremental testing before rollout
- LI.FI Widget component reference for the live component surface
FAQ
What is the simplest useful error handling setup for a LI.FI widget?
The simplest useful setup is a host-side status model with idle, running, completed, and failed states, plus subscriptions to route execution lifecycle events and clear page-level messaging outside the widget for progress, success, and failure.
Which LI.FI widget events should I wire first for failure handling?
Start with RouteExecutionStarted, RouteExecutionUpdated, RouteExecutionCompleted, and RouteExecutionFailed. Those four events usually give the clearest path to understandable user feedback and supportable analytics.
Should the host app rely only on widget UI for failures?
Usually no. The widget can surface important state internally, but the surrounding product still needs to explain what the route means in context, what the next step is, and how the user should recover when something fails.
How do I prevent users from reaching unhelpful routes?
Use product-aware constraints such as allowedChains and allowedTokens when the rest of the flow expects a narrower outcome. Prevention is usually easier than explaining a bad path after the fact.
Is wallet handling part of error handling?
Yes. Many user-visible failures begin as wallet-state confusion rather than route execution problems, so reconnect behavior, refresh states, and direct-entry expectations should all be tested before release.
When should support be part of the flow?
Support should be part of the flow when repeated failure, product constraints, or user uncertainty cannot be resolved through a clean self-service retry. If the product exposes support intent, make sure that path leads somewhere useful.
Continue from a working widget to a supportable one
Start by narrowing avoidable route mistakes, add host-side lifecycle listeners, separate progress from failure, and make the next recovery action obvious. That is what turns a working embed into a production flow that the rest of the team can actually support.
- Start with the LI.FI widget docs
- Refine route scope in the supported wallets and routing guide
- Wire host-side lifecycle handling in the event hooks guide
"One of the only full-stack Web3 component libraries i've seen in the space so far. Ten out of ten recommended. Saved me a ton of time. Can't wait to see what templates they release next."
Samy
Side projects builder