wagmi integration breaks on wallet connection and network switching
On the surface, wagmi integration looks like a dozen lines: a connection provider, an account-reading hook, a network-switching hook. It breaks not there, but on state desynchronization. The wallet changes the network on its own — from its own interface, not through a call in the app.
At that moment, the connection cache and the provider diverge: the screen renders one network, the transaction signature goes to another, and the user finds out about it from a stuck operation.
The second failure — request duplication. Several components subscribe to the same state source, and each triggers its own request to the node: balance, allowances, and the token list are fetched three or four times on a single network switch.
The node responds with rate limiting, the interface with a delay of several seconds, and the logs show a storm of identical calls.
The third — leaks on unmount. The wallet event listener keeps living after the component is removed from the page; a state update arrives in a nonexistent component, and when the page is reloaded in development mode, listeners accumulate by the dozens.
The fourth — configuration errors due to settings sprawl: the list of supported networks, contract addresses, and transport parameters live directly in components, so adding one network requires edits in a dozen files, and something is always missed.
The cost of each failure is not cosmetic: the user loses transaction confirmation, support digs through logs, and the release is delayed. Next, we break down how this is closed — with a single client, binding state to one source, and explicit network description.
What changes after careful configuration of providers and hooks
Order in the connection layer begins with all network calls going through one request cache instead of a set of custom handlers.
The share of unnecessary calls drops severalfold: balance, token list, and signature result are read from shared storage instead of being refetched on every component unmount.
On a production interface, this cut more than half of requests to the node with the same set of widgets on the page.
Cache invalidation is set explicitly — on address change, network change, or transaction completion — so data does not get stuck or lag behind chain state.
Configuring Wagmi on top of viem removes manual checks: providers are declared once, and hooks receive a consistent context instead of a dozen local states. Mount behavior is configured separately so that page navigation does not open unnecessary connections.
Network switching becomes a predictable operation: the app sees the current chain, offers a switch, and does not lose the connection if the user declines it.
Re-signing after a page reload takes one request — the connection is restored from saved state rather than rebuilt through manual provider selection.
A separate class of failures related to races on unmount goes away: requests are correctly canceled, and state is not written to a component that no longer exists.
Recovery time after a connection loss is measured by one reconnect instead of a reload — fractions of a second versus several seconds of manual return to the interface.
Methods of wagmi integration: comparing connection options
The connection method determines where the configuration lives and at what level hooks see it.
In practice, the choice comes down to four schemes: a ready-made connection provider at the app root, multiple providers in different subtrees, a custom configuration layer with multiple networks and transports, or a template binding from the library.
The difference shows up not at startup, but when adding a second network, in tests, and when switching wallets.
There are three criteria: how many networks and connection methods the scheme can withstand without edits to the component tree, whether the request cache is shared between subtrees, and how smoothly the upgrade to the next major version goes.
| Option | When it fits | Limitations of the option |
|---|---|---|
| Ready-made connection provider at the root | One network, one or two connection methods, a short path to the first request | A second network or second transport requires edits in the tree; tests need a running network node |
| Custom configuration layer | Multiple networks with different contract sets, custom transports, predictable tests | State consistency during network switching and cache invalidation rules are kept manually |
| Multiple providers in subtrees | Embedded widgets, isolated blocks on someone else's page | Hooks see only the nearest config, the cache is not shared, some requests are duplicated |
| Template binding from the library | Prototype, internal tool, one team | Upgrading to the next major version means manually editing config and types; server-side rendering requires careful hydration |
We more often choose a custom configuration layer where there is more than one network: the config is assembled in one module, and the provider receives a ready-made object — adding a network or transport does not touch components and tests.
Workflow: from configuration audit to handover of the scheme
We start not with code, but with an inventory: which networks and wallets are actually used, where connection state is stored, and how many requests to the node are sent on a cold load.
This sets the boundaries of the work and shows the places where the integration already diverges from the overall configuration.
- Connection layer audit. Providers, the set of networks and wallets, points of state reading that bypass the config. We measure the number of requests to the node on load and network switching — later it serves as a comparison point.
- Layer diagram. We separate configuration, request client, hooks, and components, and describe the relationships between them. We agree before code: otherwise migrating hooks drags along interface rewrites.
- Transport setup. Primary and backup node addresses, failover order, retry limiting, read cache. The wagmi config becomes the only place where networks and their parameters live.
- Hook migration. First reads — balances, allowances, statuses; then writes — confirmations and sending. We verify each step separately, and the previous read path runs in parallel for a while.
- Scenario checks. Node failure, rejected signature, account or network change in the middle of an operation, simultaneous requests. We expect a clear interface rollback instead of a frozen screen.
- Handover of regulations. Layer map, config with explanations, procedure for adding a new network, instructions for rolling back to the previous scheme.
Each edit stays within the boundaries of its layer — a change in one hook no longer breaks signing elsewhere.
What remains in the project: layer diagrams, configuration, and regulations
We hand over the wagmi integration not as a folder of code, but as a set of artifacts that your team uses to continue the work without us.
Each item below is a working document, not a box-ticking report: it can be used to update dependencies, investigate incidents, and onboard a new developer to the project.
- Dependency map — what is connected, why exactly, which packages are related to each other, and what can be updated independently.
- Layer diagram — where the connection configuration lives, where the hooks are, where the view is: it immediately shows what replacing a wallet or network affects.
- Connection configuration — the list of networks and providers, priority order, behavior when the node is unavailable, and timeouts.
- Hook documentation — purpose, inputs and return values, cache, side effects, and places where unnecessary re-rendering occurs.
- Error handling policy — failure classes, retries, what the user sees, what goes to logs and alerts, and what is suppressed silently.
- Update regulation — the procedure for moving to a new major branch of the library, a verification checklist, and criteria for rolling back to the previous release.
- Test harness — a mock provider and a set of scenarios on which changes are run before production.
Everything lies next to the code and is versioned together with it, so the documentation does not diverge from the implementation.
Your engineer opens the layer diagram, finds the needed hook, and understands where to change behavior — without messaging us and digging through commit history.
Case study: the connection layer was rewritten and unnecessary requests were removed
The project is a user dashboard with wallet connection and a status panel.
Each component pulled network and balance data with its own hook: the same query went to the network from six to eight places, state was polled independently, and during desynchronization neighboring screens showed different numbers.
The share of repeated requests to the node reached 40%, and almost every third support request began with "the balance didn't update."
The connection layer was rewritten on Wagmi: a unified configuration with multiple connection sources and automatic failover to a backup, reads via subscriptions instead of timer polling, cache by request keys, and deduplication of simultaneous calls.
The migration to the current major branch was carried out without stopping releases — hooks were replaced one screen at a time, and both implementations were kept side by side until the checks passed.
What changed: the share of repeated requests fell from 40% to 7%, and recovery time after node failure — from half an hour of manual switching to four minutes of automatic failover. Support requests about desynchronization dropped from ninety to twelve per month.
The failure class also changed. Instead of discrepancies between screens and stuck states, external connection failures remain — they are visible in logs immediately and do not require manual diagnostics.
That is the practical point of the migration: the connection stopped being a source of random errors.
What to do if the project is already on an old major version
Yes, migrating to a new major version of wagmi can be done in stages — but not with two copies of the library in one build. The package is one, and two versions conflict over provider context: components get either one client or the other, and errors become intermittent.
The working scheme is to stand up a new layer alongside and connect it module by module or route by route, not all at once across the entire application.
The order of completion is dictated by the cost of error. Configuration comes first: createConfig with explicit transports instead of the previous configureChains.
Next is reading, useReadContract instead of the old read hooks: this layer holds almost no state, so it is migrated without risk to user scenarios.
Then writing: useWriteContract together with useSimulateContract — simulation before sending a transaction reduces the share of reverts and gas failures, and writing should not be migrated as a batch without it.
The queue is closed by wallet and network: connectors in the config, chain and useSwitchChain instead of useNetwork, which no longer exists in the new branch.
To let the old and new layers live simultaneously, an adapter is placed between them: wrappers with an unchanged signature, under which the implementation changes.
Components do not know which version is underneath, and migration proceeds one route at a time — backward compatibility is maintained until the last module.
The main breaking changes are concentrated in configuration, wallet connection, and network hooks — they are addressed first. After that, discipline takes over: each migrated module removes its wrapper, otherwise the two layers remain in the code forever.
Technical concerns: cache, unmounting, network switching
In Wagmi hooks, the cache runs on two independent timers: while data is fresh, the request is not repeated on every render, and after unmounting the result stays in memory until the second interval expires.
A typical defect is a stale balance after a transaction: the request key contains neither the network nor the account address, and the response from one chain goes to the interface of another.
The second common objection is double signing. Usually the issue is not the wallet, but the code: the handler is attached to an element that re-renders, and the sending flag is not fixed anywhere.
How is cache lifetime configured?
By two parameters: freshness period and lifetime after unmounting. We set a common value once, and for balances and allowances we override it on the hook.
Why does the wallet ask for a signature twice?
The button is not blocked during confirmation, and the signing state lives in a component that unmounts. We move the call into a separate handler and prevent a second run until the current one completes.
What to do about desynchronization after a network switch?
We include the network and wallet address in the request key so that data from one chain is not shown on another. We attach cache invalidation to network or account changes.
How does the integration behave during a network outage?
Requests are retried with increasing delay, and when connectivity is restored, state is refetched automatically. Provider markup at the top level does not break current components.
Let's discuss the task: what to send for an estimate and work plan
To make the work estimate based on facts rather than guesses, for the first step it is enough to send several artifacts — without production access, secret keys, or user data.
- a link to the repository or an archive of the frontend part: we are interested in the folder with wallet connection and provider structure;
- dependency files with pinned versions — they show which branch of the library the current wagmi integration is built on and what will have to be pulled along with it;
- a list of supported networks and methods of access to them (public nodes, own nodes, backups) — without the keys themselves;
- a description of the current hooks: where balances and account state are read, where writes to contracts go, how loading, error, and repeated request are handled;
- a list of scenarios that already break or slow down: connection loss, network switch, parallel requests, re-entry;
- requirements for server-side rendering and cache, if the application serves ready-made markup;
- the current acceptance list or tests, if any.
This is enough to estimate the scope: which hooks are rewritten, what is migrated to the new version, and where stubs are needed during the transition.
Then we come back with a work estimate and implementation plan — the order of stages, rollback points at each, and the composition of the documentation handover at the end.
The next step is simple: you send what you have, we review it and set up a substantive conversation — what we do first, what can be postponed, and where we are taking risks.