Atlas fails with "Plugin directory <path> is missing package.json or index file" because resolvePathPluginTarget requires either a package.json or a resolvable directory index at the plugin path, and neither was found. Add a package.json with a main or exports entry, or an index file, at the plugin path, and point the plugin spec at the plugin's root directory rather than at a parent. Restart Atlas so the plugin loader re-resolves the target.
Why does Atlas say the plugin directory is missing package.json or index file
Atlas says "Plugin directory <path> is missing package.json or index file" because resolvePathPluginTarget accepts exactly 2 kinds of entry point at a plugin path: a package.json, or a resolvable directory index. When neither exists at the path in the message, Atlas cannot resolve the plugin and refuses to load it.
Atlas is extensible through plugins that contribute tools and hook into agent lifecycle events, and every plugin has to declare an entry point Atlas can actually load. A path-based plugin spec points at a directory, and Atlas looks inside that directory for one of the two accepted entry shapes. Nothing else counts. A directory full of source files with no package.json and no index file is not a loadable plugin, no matter how correct the code inside it is. The path in the error message is the exact directory Atlas looked in.
How to fix the missing plugin entry point in Atlas
Fix the Atlas plugin entry error by adding a package.json with a main or exports entry, or an index file, at the plugin path. Atlas resolvePathPluginTarget requires 1 of those 2 things, so supplying either one makes the plugin resolvable.
Prefer the package.json route for anything beyond a throwaway plugin, because a package.json with a main or exports entry states the entry point explicitly and survives file reorganization inside the plugin. The index file route is the quicker option for a small local plugin where the directory index is the obvious entry. Whichever you choose, put it at the exact path named in the error, not one level up or down. Then restart Atlas so the plugin loader re-resolves the target, because the resolution happens at load time.
Why the Atlas plugin spec must point at the plugin root
Point the Atlas plugin spec at the plugin's root directory, not at a parent. Atlas resolvePathPluginTarget accepts 1 of 2 things at exactly the path the spec names, a package.json or a resolvable directory index, so a spec aimed at a parent directory finds neither and raises the missing entry error.
Pointing at a parent is one of the most common ways to produce this error while having a perfectly valid plugin sitting one level below. A monorepo makes it especially easy: the workspace root has no plugin entry point, while the actual plugin package does. Read the path Atlas printed in the error message and compare it against where the plugin's package.json actually lives. If they differ, the spec is the bug, not the plugin, and correcting the path in the spec fixes the load with no changes to the plugin itself.
What "resolved entry outside plugin directory" means in Atlas
Atlas raises "Plugin <spec> resolved <kind> entry outside plugin directory" as a path-escape guard: resolvePackageFile refuses any entry that resolves outside the plugin's own directory. In 2026 the fix is to correct the package exports map, which is pointing at a file beyond its own folder.
The escape error is a different problem from the missing entry error, even though both come from plugin resolution. Here the plugin has an entry, but the entry resolves somewhere Atlas will not follow. Fix the package exports map: it is escaping its own folder. That usually means an exports or main value with a relative path that climbs out of the plugin directory, often left over from a build layout where the compiled output lived elsewhere. Point the exports map at files inside the plugin directory and reload.
How to verify the Atlas plugin loads after the fix
Verify the Atlas plugin fix by restarting Atlas so the plugin loader re-resolves the target. Success means 0 of the 2 errors appear, neither "Plugin directory <path> is missing package.json or index file" nor "resolved <kind> entry outside plugin directory", and the plugin's tools are available to the agent.
Restart is not optional here. Atlas resolves the plugin target when the loader runs, so adding a package.json to the plugin directory while Atlas is already running changes nothing until the process restarts and resolvePathPluginTarget looks again. If the missing entry error reappears with the same path, the entry you added is not at that path. If the escape error appears instead, resolution now succeeds and you have moved on to the exports map, which is progress rather than a regression.
Which entry points does an Atlas plugin directory need
An Atlas plugin directory needs 1 of exactly 2 entry points: a package.json carrying a main or exports entry, or a resolvable directory index file. Atlas resolvePathPluginTarget checks for those two and raises the missing entry error when the directory offers neither.
Knowing the accepted shapes up front prevents a lot of guessing. A plugin directory containing only TypeScript sources, only a README, or only a nested package one level down will not resolve. The entry point has to sit at the plugin path itself. Additionally, whatever the package.json main or exports entry names must resolve inside the plugin's own directory, because Atlas resolvePackageFile refuses any entry that resolves outside it. Meet both conditions, restart Atlas, and the plugin loader will resolve the target and load the plugin's tools.
How to fix it
- 01Add a package.json with a main/exports entry, or an index file, at the plugin path.
- 02Point the plugin spec at the plugin's root directory, not at a parent.
- 03If you see the "outside plugin directory" error, fix the package exports map: it is escaping its own folder.
- 04Restart Atlas so the plugin loader re-resolves the target.
Frequently asked questions
- How do I fix "Plugin directory is missing package.json or index file" in Atlas?
- Add a package.json with a main or exports entry, or an index file, at the plugin path, then restart Atlas so the plugin loader re-resolves the target.
- What entry point does an Atlas plugin directory need?
- Atlas resolvePathPluginTarget requires either a package.json or a resolvable directory index at the plugin path. A directory with neither cannot be loaded as a plugin.
- Why does Atlas not find my plugin even though the code is there?
- Point the plugin spec at the plugin's root directory, not at a parent. Atlas looks for the entry point at exactly the path the spec names, so a spec aimed one level up finds nothing.
- What does "resolved entry outside plugin directory" mean in Atlas?
- Atlas resolvePackageFile refuses any entry that resolves outside the plugin's own directory, which is a path-escape guard. Fix the package exports map, because it is escaping its own folder.
- Do I need to restart Atlas after adding a plugin package.json?
- Yes. Restart Atlas so the plugin loader re-resolves the target. Resolution happens at load time, so a package.json added while Atlas is running has no effect until the process restarts.
- Can an Atlas plugin point its main entry outside its folder?
- No. Atlas refuses any entry that resolves outside the plugin's own directory and raises "Plugin <spec> resolved <kind> entry outside plugin directory". Keep the exports map inside the plugin folder.
- Is an index file enough for an Atlas plugin, or do I need package.json?
- Either works. Atlas resolvePathPluginTarget accepts a package.json with a main or exports entry, or a resolvable directory index file, at the plugin path.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with GPT-OSS 120B (local via Ollama): Offline Reasoning for Air-Gapped Work in 2026
GPT-OSS 120B is the strongest fully offline reasoning model for Atlas: a 65GB MXFP4 download, 131,072 token context, free self-hosted, or $0.15 / $0.60 per Mtok on Groq.
Atlas with Llama 3.3 70B Instruct (Meta Llama API) in 2026
Llama 3.3 70B Instruct (Meta Llama API) in Atlas for 2026: 128,000 tokens of context, an OpenAI-compatible endpoint, and a 4,096 token output ceiling to plan around.
Atlas for PHP in 2026
Atlas, the terminal-native AI coding agent, empowers PHP developers in 2026 with intelligent code understanding, secure workflows, and direct integration for Composer and PSR standards.
Atlas with GPT-OSS 20B (local via Ollama): Local Reasoning on a 16GB Card in 2026
GPT-OSS 20B is OpenAI's open-weight reasoning model: 131,072 token context, runs on a single 16GB GPU, free self-hosted, or $0.075 / $0.30 per Mtok via Groq.
Atlas with Qwen3 235B-A22B: Flagship Sparse Reasoning in 2026
Qwen3 235B-A22B in Atlas: 235B total parameters, 22B active per token, $0.70 per Mtok input and $2.80 per Mtok output, 128K tokens (131,072) of context.
Atlas with Llama 3.1 70B (local via Ollama): A 43GB Private Agent in 2026
Llama 3.1 70B (local via Ollama) in Atlas for 2026: a 43GB pull for a 48GB GPU or 64GB Mac, Free (self-hosted), with 128,000 tokens of context on your own hardware.
Atlas with DeepSeek R1 (0528): The Open Reasoning Trace, 2026
Run Atlas on DeepSeek R1 (0528) in 2026. DeepInfra hosts the MIT-licensed open reasoning model at $0.50 per Mtok in, $2.15 per Mtok out, 160K tokens context.
Atlas with GLM-4.6: 200K Open Weights at the 4.5 Price in 2026
GLM-4.6 runs Atlas on a 200K tokens (204,800) context at $0.60 per Mtok input and $2.20 per Mtok output, the same price GLM-4.5 charged on a 128K window.