Atlas fails to load a plugin with "Plugin requires atlas <range> but running <version>" because checkPluginCompatibility reads engines.atlas from the plugin's package.json and throws when semver.satisfies fails against your running Atlas version. Fix it by upgrading or downgrading Atlas to a version inside the plugin's declared range, or by updating the plugin to one that declares support for your Atlas version. The check is skipped for 0.x Atlas versions and for invalid version strings.
Why does Atlas say a plugin requires a different version
Atlas says "Plugin requires atlas <range> but running <version>" because checkPluginCompatibility reads the engines.atlas field from the plugin's package.json and throws when semver.satisfies fails. The check is skipped for 0.x Atlas versions and for invalid version strings, so it only fires on a real range mismatch.
The comparison is a straight semver check with no fuzziness. Atlas reads engines.atlas out of the plugin's package.json, runs semver.satisfies against the running Atlas version, and throws when the answer is false. Both halves of the message are therefore literal facts: the range came from the plugin author, and the version came from your installation. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, which is exactly why a plugin built against the wrong Atlas version is refused rather than loaded and allowed to misbehave at runtime.
How to fix a plugin version incompatibility in Atlas
Fix the Atlas plugin version error in 1 of 2 ways: upgrade or downgrade Atlas to a version inside the plugin's declared range, or update the plugin to one that declares support for your Atlas version. Both make semver.satisfies return true, which is all checkPluginCompatibility asks.
Prefer updating the plugin when a newer plugin release exists, because pinning Atlas to an old version to satisfy one plugin drags every other plugin and every Atlas improvement backward with it. Move Atlas instead when the plugin is unmaintained and the range it declares is genuinely correct for the API it uses. Read the range in the error message before choosing, because it tells you exactly which Atlas versions the plugin author believes are safe, and whether your current version is above or below that window.
How to read the engines.atlas field on an Atlas plugin
Check the plugin's engines.atlas field in its package.json. Atlas checkPluginCompatibility reads exactly that 1 field and feeds it to semver.satisfies, so engines.atlas is the single source of the range printed in the "Plugin requires atlas <range>" error, and an overly narrow range there is a plugin bug.
An overly narrow engines.atlas range is a plugin bug, not an Atlas bug, and it is worth saying plainly. A plugin that pins a single exact Atlas version, or that declares a range far tighter than the API surface it actually touches, will break on every routine Atlas upgrade for no good reason. If you own the plugin, widen the range to what the plugin genuinely requires. If you do not own it, the engines.atlas value tells you what to report upstream, and it tells you precisely which Atlas versions will load the plugin in the meantime.
When Atlas skips the plugin compatibility check
Atlas skips the plugin compatibility check in 2 cases: for 0.x Atlas versions, and for invalid version strings. checkPluginCompatibility does not run semver.satisfies in either case, so a plugin that loads fine on a 0.x build can still fail once Atlas is on a version the check applies to.
The skip explains a confusing class of report: a plugin that worked yesterday failing today after an Atlas version change, with no plugin change at all. If the previous Atlas version was 0.x, no compatibility check ever ran, and the plugin's engines.atlas range was never tested against anything. Moving off 0.x turns the check on, and an inaccurate range surfaces immediately. The same applies to an invalid version string. The plugin was not silently compatible before, it was simply unchecked.
How to get Atlas running immediately when a plugin blocks startup
Remove the plugin from config if you need Atlas to start right now. With the plugin gone, checkPluginCompatibility never reads its engines.atlas field, so the throw does not happen and Atlas starts in 2026 with the remaining plugins loaded. Fix the version range afterward, not under pressure.
Removing the plugin from config is a stopgap, and honesty about that matters: you lose whatever the plugin contributed. Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, so dropping one may remove tools the agent was relying on. Use the removal to get unblocked, then do the real fix, which is either moving Atlas into the plugin's declared range or updating the plugin to a release that supports your Atlas version. Re-add the plugin to config afterward and confirm it loads.
How to verify the plugin compatibility fix worked
Verify the Atlas fix by restarting Atlas and confirming the plugin loads without the "Plugin requires atlas <range> but running <version>" message. Success means checkPluginCompatibility ran semver.satisfies against engines.atlas, the comparison passed, and Atlas started with 0 plugin compatibility errors.
If the error returns with a different range in the message, you updated to a plugin release whose engines.atlas declares a different window, and your Atlas version still falls outside it. If the error returns with a different version in the message, the Atlas version change did not take effect in the process that is loading the plugin. Read both halves of the message on every retry, because the range and the version together tell you which side moved and whether it moved far enough.
How to fix it
- 01Upgrade or downgrade Atlas to a version inside the plugin's declared range.
- 02Or update the plugin to one that declares support for your Atlas version.
- 03Check the plugin's engines.atlas field; an overly narrow range is a plugin bug, not an Atlas bug.
- 04Remove the plugin from config if you need Atlas to start right now.
Frequently asked questions
- How do I fix "Plugin requires atlas but running" in Atlas?
- Upgrade or downgrade Atlas to a version inside the plugin's declared range, or update the plugin to one that declares support for your Atlas version. Either makes semver.satisfies pass.
- What is engines.atlas in an Atlas plugin?
- engines.atlas is the field in a plugin's package.json that declares which Atlas versions it supports. Atlas checkPluginCompatibility reads it and throws when semver.satisfies fails against the running version.
- Why did my Atlas plugin work before and break after an upgrade?
- The compatibility check is skipped for 0.x Atlas versions and for invalid version strings. If you were previously on a 0.x build, engines.atlas was never checked, and moving off 0.x turns the check on.
- Is a narrow engines.atlas range an Atlas bug?
- No. An overly narrow range is a plugin bug, not an Atlas bug. Check the plugin's engines.atlas field and report or widen it if it is tighter than the API the plugin actually uses.
- How do I start Atlas when a plugin blocks it?
- Remove the plugin from config if you need Atlas to start right now. Atlas will not read that plugin's engines.atlas field, so the version throw does not fire and Atlas starts.
- Should I downgrade Atlas or update the plugin?
- Prefer updating the plugin to one that declares support for your Atlas version. Downgrading Atlas to satisfy one plugin drags every other plugin and every Atlas improvement backward with it.
- Where does the version range in the Atlas plugin error come from?
- The range comes from the plugin's engines.atlas field in package.json, read by Atlas checkPluginCompatibility. The version in the message is the Atlas build you are actually running.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas for dbt: Terminal-Native AI Coding in 2026
Atlas is a terminal-native AI coding agent for dbt. Read the ref() DAG, convert a table model to incremental, run dbt build against dev, and add tests in 2026.
Atlas with Databricks Foundation Model APIs in 2026: Frontier Models Inside the Lakehouse
Atlas with Databricks Foundation Model APIs in 2026: Claude Opus 4.7 at a 1,000,000 token context, GPT-5.5 at 1,050,000, governed by the same DATABRICKS_TOKEN.
Atlas with GPT-OSS 20B (hosted): the cheap slot that can still think in 2026
Run Atlas on GPT-OSS 20B (hosted) in 2026: $0.03/$0.14 per Mtok on DeepInfra, a 131,072 token context, reasoning on, and $0.00/$0.00 locally in LM Studio.
Atlas for PowerShell: A Terminal-Native AI Coding Agent for Modules and Pester in 2026
Atlas is a terminal-native AI coding agent for PowerShell in 2026. It reads your .psm1 module and .psd1 manifest, adds SupportsShouldProcess, and runs Invoke-Pester behind a prompt.
Atlas with Phi-4 Mini 3.8B (Ollama): Native Function Calling at 2.5GB in 2026
Phi-4 Mini 3.8B (Ollama) is a 2.5GB model with 128K tokens (131,072) of context and native function calling, Free (self-hosted). The Atlas small_model that can route tools.
Atlas with GPT-5.3 Chat: The small_model Slot Pick for 2026
GPT-5.3 Chat is a non reasoning 128K model at $1.75 per Mtok input, $14 per Mtok output. Why it belongs in the Atlas small_model slot, not the main build loop.
Atlas with GPT-OSS 120B (hosted): picking the right host in 2026
Run Atlas on GPT-OSS 120B (hosted) in 2026. Identical Apache weights cost $0.037 per Mtok on DeepInfra and $0.35 on Cerebras, a 9.5x input spread. Full host guide.
Atlas for TypeScript in 2026
In 2026, TypeScript developers leverage Atlas, the terminal-native AI coding agent, to enhance productivity. Atlas understands your types, ensures code quality, and offers robust safety features.