# Atlas error: Plugin requires atlas but running > 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. Atlas fails to load a plugin with "Plugin requires atlas but running " 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. ## Symptom Loading a plugin in Atlas fails with: Plugin requires atlas but running . The plugin does not load, and Atlas names both the declared range and the version it is actually running. ## Cause Atlas checkPluginCompatibility reads engines.atlas from the plugin package.json and throws when semver.satisfies fails against the running Atlas version. The check is skipped for 0.x Atlas versions and for invalid version strings, so it only fires on a real, satisfiable comparison. ## Fix 1. Upgrade or downgrade Atlas to a version inside the plugin's declared range. 2. Or update the plugin to one that declares support for your Atlas version. 3. Check the plugin's engines.atlas field; an overly narrow range is a plugin bug, not an Atlas bug. 4. Remove the plugin from config if you need Atlas to start right now. ## Why does Atlas say a plugin requires a different version Atlas says "Plugin requires atlas but running " 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 " 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 but running " 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. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/plugin-version-incompatible Source of truth: aeo_pages row `/resources/troubleshooting/plugin-version-incompatible` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.