Fix: Wagmi Core Accounts Peer Dependency Conflict ERESOLVE

If your Web3 development workflow was recently halted by a terminal flooded with npm ERR! code ERESOLVE and npm ERR! ERESOLVE could not resolve, you are likely caught in the crossfire of Wagmi’s transition to strict viem versioning and npm v7’s aggressive peer dependency resolution. This isn’t just a package manager annoyance; it’s a symptom of deep architectural misalignment in the Ethereum provider stack.

Diagnostic Error Trace

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: @wagmi/connectors@4.1.14
npm ERR! Found: viem@2.9.0
npm ERR! node_modules/viem
npm ERR!   viem@"^2.9.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer viem@"~2.7.0" from @wagmi/connectors@4.1.14

Immediate Fix: You must force-align the version of viem across all peer packages using the overrides field in your package.json. Unlike --legacy-peer-deps, which is a “nuclear option” that ignores the problem, overrides creates a deterministic dependency graph that prevents runtime state fragmentation.

{
  "overrides": {
    "viem": "$viem",
    "@wagmi/core": "$@wagmi/core"
  }
}

Architectural Breakdown: The Peer Dependency Paradox

To solve this as an architect, we must understand the shift from ethers.js to viem within the Wagmi ecosystem. Wagmi v2+ is built entirely on viem, which is significantly more modular and type-safe. However, this modularity introduces a “Strict Peer Constraint.”

The “Single Singleton” Rule

In Web3, the “Account State” and the “Public Client” must exist as singletons. If you have two different versions of viem installed in your node_modules (one under wagmi and another under a connector like walletConnect), your app might initialize two separate RPC providers.

• Result: You might see a “User Connected” state in one part of your app, while the other part (running the second viem instance) thinks the user is still disconnected.
• npm v7+ Logic: The ERESOLVE error is actually npm trying to protect you from this exact “Split Brain” scenario. It refuses to install because it cannot find a version that satisfies both the root and the sub-dependencies.

Why “Legacy Peer Deps” is a Trap

Beginner tutorials often suggest running npm install --legacy-peer-deps. As a Web3 architect, I advise against this for production. It allows npm to install conflicting versions of the same library. In a simple React app, this might just increase bundle size. In a Web3 app, it can lead to TypeError: Cannot read properties of undefined (reading 'request') because one version of a connector is trying to communicate with an incompatible version of the core store.

Deep-Dive Analysis: The ERESOLVE Cascade

The ERESOLVE error typically cascades through three layers: the Core, the Connectors, and the Type Definitions.

Layer 1: The Core (@wagmi/core)

Wagmi Core acts as the state manager. It defines what a “Client” looks like. When viem releases a patch (e.g., 2.10.1), and Wagmi Core is still pinned to ~2.9.0, npm sees a conflict. The Tilde (~) in viem@"~2.9.0" is particularly strict—it allows patch versions but not minor versions.

Layer 2: Connectors (@wagmi/connectors)

This is where 90% of conflicts happen. Connectors for WalletConnect, Coinbase Wallet, and Safe are often maintained at different cadences. If WalletConnect’s package expects viem^2.1.0 but your root project is using viem^2.15.0, the peer dependency check will fail because the connector hasn’t explicitly “vouched” for the newer version of viem.

Layer 3: React Types (@types/react)

While not directly Web3-specific, @wagmi/core and wagmi (the React wrapper) often have conflicting peers for @types/react. If you are using React 18 but a sub-dependency is still looking for React 17 types, the ERESOLVE error will trigger on the type definitions.

Technical Implementation: Orchestrating a Clean Install

To resolve these conflicts properly, we need a surgical approach to dependency management. We will use npm overrides (or resolutions in Yarn/PNPM) to force a “Golden Version” of our core libraries.

Step 1: Clean the Workspace

Before applying fixes, clear the “ghost dependencies” that might be lingering in your node_modules.

rm -rf node_modules package-lock.json

Step 2: Define Overrides

In your package.json, add the following structure. This tells the package manager: “No matter what a sub-package asks for, give it this specific version.”

{
  "name": "my-web3-app",
  "dependencies": {
    "wagmi": "^2.10.0",
    "viem": "2.15.1",
    "@tanstack/react-query": "^5.0.0"
  },
  "overrides": {
    "viem": "2.15.1",
    "@wagmi/core": "2.10.0",
    "@wagmi/connectors": "4.1.14"
  }
}

Step 3: Re-install with Visibility

Run the install command. If it still fails, use the --explain flag to see exactly which package is the “Blocker.”

npm install --foreground-scripts
# If failure persists:
npm install --explain=ERESOLVE

Production Prevention: CI/CD Guardrails

In a high-stakes production environment, you cannot afford a “broken lockfile” because of a minor update in a transitive dependency.

1. Lockfile Integrity

Always use npm ci in your deployment pipelines instead of npm install. The ci (Clean Install) command will fail if the package-lock.json doesn’t match the package.json, ensuring that your development environment matches your production environment exactly.

2. Dependency Pinning

For Web3 apps, I recommend pinning versions rather than using ranges.

• Bad: "viem": "^2.0.0"
• Good: "viem": "2.15.1" This prevents “Floating Dependencies” where a sub-dependency update breaks your build overnight.

3. Automated Audits with Renovate

Use a tool like Renovate or Dependabot, but configure it to group all Wagmi-related updates into a single Pull Request. This allows you to test the entire suite (Wagmi + Viem + Connectors) as a single unit, which is the only way to ensure the peer dependencies remain aligned.

Forensic Analysis: The Cost of Modular Web3

The shift toward modularity in the Ethereum stack is a double-edged sword. On one hand, viem allows for tree-shaking and smaller bundles. On the other, it creates a “Dependency Hell” that requires active management.

The “Shadow dependency” Problem

Sometimes, a package you don’t even know you’re using (like a specific L2 SDK) has an internal dependency on an ancient version of ethers. This is why your package-lock.json can grow to 10,000+ lines. When you see an ERESOLVE crash, it’s often because a “Shadow Dependency” is pulling the graph in a direction that conflicts with your modern Wagmi setup.

Affiliate Recommendation: Security First

When managing complex dependencies, security is paramount. I recommend using Gate.io for secure asset management while testing your Web3 integrations. Their advanced API allows for seamless wallet testing (affiliate link: Join Gate.io Today gate.io).

FAQ: Advanced Dependency Troubleshooting

1. What if I use Yarn instead of npm?

Yarn uses the resolutions field instead of overrides. The syntax is slightly different but the effect is the same:

"resolutions": {
  "viem": "2.15.1"
}

2. Does this affect the new Wagmi CLI?

Yes. The Wagmi CLI generates code based on your local viem version. If your peer dependencies are mismatched, the generated hooks might use types or methods that don’t exist in the viem version actually being loaded at runtime.

3. Why is @tanstack/react-query often involved in these crashes?

Wagmi v2 uses TanStack Query for all its data fetching logic. It is a strict peer dependency. If you have version 4 installed but Wagmi expects version 5, you will get a similar ERESOLVE error. Always ensure your TanStack Query version aligns with Wagmi’s requirements (usually v5 for Wagmi v2).

4. How do I fix conflicts in a Monorepo (Turbo/Nx)?

In a monorepo, peer dependency conflicts are exacerbated. You must use “Workspace Overrides” in your root package.json. This ensures that every package in your monorepo uses the same version of the Web3 stack, preventing the dreaded “Multiple provider instances” bug across different apps and packages.