AI Agent

How to Fix Dependency Conflicts (Python/Node.js)

July 16, 2026 · 6 min read · YayaAgent Team

Most people picture "dependency conflicts" as one generic error message — something's broken, reinstall and hope. In practice it's usually one of three distinct problems: the wrong runtime version (Node or Python), a native module that failed to compile against your OS, or two packages disagreeing about which version of a shared dependency they need. Each has a different fix, and treating all three the same way — usually "just reinstall everything" — is why the same error tends to come back a week later.

OpenClaw and n8n both sit on the same underlying stack — Node.js and npm — so the same handful of failure modes show up in both, just with different version numbers and commands. Hermes runs on Python instead, which means a genuinely different set of problems (and this is the one worth reading in full if you're hitting a wall there, rather than assuming it's "basically the same as Node"). We'll go deep on the Node.js layer once, using OpenClaw as the example, then point out exactly what changes for n8n rather than re-explaining the same mechanism twice.

Quick Diagnosis

Symptom	Likely Cause
Install fails immediately with an "engine" or "unsupported" error	Wrong Node.js or Python version
Install runs a long time, then fails with `gyp ERR!` or a compile error	A native module failed to build against your OS/architecture
Install succeeds, `command not found` afterward	PATH issue, not actually a dependency conflict
Install fails with `ERESOLVE` or a peer dependency error	Two packages want incompatible versions of the same shared dependency
Everything installed, but running it throws `ModuleNotFoundError` or similar	A partially-completed install or a corrupted virtual environment

1. The Node.js Layer (OpenClaw)

OpenClaw requires Node.js 22 or newer — it uses language features (native WebSocket, import attributes, the newer module resolution algorithm) that don't exist in Node 18 or 20. This is, by a wide margin, the single most common cause of install failures, and it's worth understanding why rather than just running the fix: Node itself doesn't silently downgrade features, so a tool built against 22 will fail in ways that look unrelated to version at all — a build error, a runtime crash, sometimes nothing more specific than "command not found." Checking the version first saves a lot of guessing:

node --version

If it's below v22, the fix is nvm, not a system-wide reinstall — reinstalling Node directly tends to create permission conflicts between versions that are more annoying to untangle than the original problem:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
nvm use 22
nvm alias default 22

Two other errors show up often enough to name directly, because they get misread as version problems when they aren't:

spawn git ENOENT — this isn't a Node version issue at all. npm is trying to pull a dependency straight from a GitHub repo and can't find git on the system. Install it (apt install git / brew install git) and retry.
command not found after a successful install — also not a dependency conflict. npm's global bin directory simply isn't on your PATH. Never fix this with sudo, which creates root-owned files that quietly break future installs:

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

Once you're on Node 22+ and PATH is sorted, run the built-in health check rather than continuing to guess:

openclaw doctor

This confirms Node version, checks for git, validates your openclaw.json, and checks required ports — during the installation steps described in the OpenClaw installation guide, this is the command worth running before assuming something deeper is wrong.

Same mechanism, different specifics: n8n

n8n hits the identical Node/npm failure modes above — wrong engine version, ERESOLVE peer conflicts, native module compile errors — just with its own version window and its own extra wrinkle. The differences that actually matter:

n8n's supported range is Node 20.19–24.x, not 22+. The fix is the same nvm approach, just pinned to a different version: nvm install 20 && nvm use 20 && nvm alias default 20.
If you switch Node versions but don't reinstall n8n afterward, its native modules stay compiled against the old ABI and fail in ways that look unrelated to version entirely. That needs a forced clean rebuild: rm -rf $(npm root -g)/n8n && npm cache clean --force && npm install -g n8n.
Its peer-dependency conflicts are almost always in optional AI/LangChain packages that don't touch core workflow execution — npm install -g n8n --legacy-peer-deps resolves the large majority of them before you'd need the blunter --force.

If you're setting up n8n fresh rather than fixing an existing install, the n8n installation guide covers local, Cloud, and server paths — the Docker route in particular sidesteps native module compilation entirely, since everything ships pre-built inside the image.

This same npm/Node mechanism is also why the fixes above generalize past just these two tools — if you're running other Node-based agent CLIs (Codex CLI, Kilo Code, and similar), a version mismatch or peer conflict there tends to resolve the same way: check the required Node version first, then treat compile errors and peer conflicts as the separate problems they are.

2. The Python Layer (Hermes)

This is where the Node.js playbook above stops applying — Python's dependency model works on genuinely different assumptions, so it's worth reading this section in full rather than pattern-matching from the section above.

Hermes requires Python 3.11 specifically (not 3.12, not 3.13) — its own installer uses uv to manage this automatically, so in most cases you don't need to install Python yourself. The conflict that trips people up most often isn't the version, though — it's environment isolation, which doesn't have a real equivalent in the npm world.

On Ubuntu 24.04, Debian 12+, and other recent distros, you'll likely hit this the first time you try pip install directly:

error: externally-managed-environment
× This environment is externally managed

This is PEP 668 working as intended — it's stopping you from installing Python packages system-wide, where they could silently break other tools that depend on the system's own Python. The fix is a virtual environment, not the --break-system-packages flag some error messages suggest as an escape hatch — that flag exists for genuine edge cases, and reaching for it by default tends to recreate the exact problem PEP 668 is designed to prevent:

python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

Or, since Hermes' own installer already handles this with uv:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

This handles Python 3.11, the virtual environment, and every other dependency (Node.js v22 for the WhatsApp bridge, ripgrep, ffmpeg) in one pass — during the Hermes installation guide, this is the path that avoids the PEP 668 error entirely rather than working around it afterward.

One rule worth internalizing regardless of which path you take: never run sudo pip install. It writes into system-level directories, and it's a common root cause of conflicts that are genuinely hard to trace later, because the symptoms tend to show up in unrelated tools first, not in Hermes itself.

When It's Not Actually a Dependency Problem

Two failure modes get misdiagnosed as dependency conflicts often enough to call out directly, regardless of which stack you're on.

If your environment is clean — right runtime version, no compile errors, no peer conflicts — but the agent still can't connect to its model provider, check auth errors next rather than continuing to reinstall packages that were never the problem.

And if everything installs and runs but feels sluggish rather than broken, that's a different guide entirely — dependency issues can also cause latency problems, but a slow-but-working agent and a broken install have different root causes and different fixes.

Myth vs. Reality

Myth: A dependency conflict means something is fundamentally wrong with the package or the framework.

Reality: The overwhelming majority of these errors trace back to one of three boring, well-understood causes — wrong runtime version, a native module that needs a compiler toolchain your system doesn't have, or two packages disagreeing about a shared version. Think of it less like a mystery to debug from scratch, and more like checking tire pressure before assuming the engine's failed — the fix is almost always smaller than the symptom suggests, and it's usually the same handful of causes wearing a different tool's name.

Troubleshooting

Symptom	Fix
OpenClaw fails to install or start silently	Check `node --version` — must be 22+; use `nvm` to upgrade, not a system-wide install
n8n aborts with "Node.js version ... not supported"	Pin to Node 20 with `nvm`; rebuild native modules after switching versions
`ERESOLVE` peer dependency error (n8n)	Try `npm install -g n8n --legacy-peer-deps` before reaching for `--force`
`gyp ERR!` during install (n8n or OpenClaw)	Missing compiler toolchain — install `build-essential python3` (Linux), or switch to a Docker image to skip compilation entirely
`externally-managed-environment` error (Hermes)	Use a virtual environment (`python3 -m venv` or the official installer) — never `--break-system-packages`
Clean environment, still can't connect	Not a dependency issue — check API keys and auth next

Bottom Line

Dependency conflicts almost always resolve into one of three causes: the wrong runtime version, a native module that needs a compiler your system doesn't have, or two packages disagreeing about a shared dependency. OpenClaw and n8n share the same underlying Node.js mechanism, just with different version windows and commands — understand it once and both (plus most other Node-based agent tools) follow the same playbook. Hermes runs on a genuinely different stack, where Python's environment isolation is the piece worth understanding on its own terms. If the environment turns out clean but something still doesn't work, that's usually an auth problem or a performance one, not a dependency one.