Troubleshooting

Most problems with the Athenode CLI, an installed setup or the Athenode MCP server come from the directory a command runs in, the project token, the project's plan or an environment variable. Look for the message or the behaviour you see among the headings, then follow the fix under it.

Athenode CLI commands that fail

An error that starts "athenode config not found"

The command ran in a directory that has no .athenode/config.json, the file in which init stores the connection to your project.

Change to the directory where you ran init, which is normally the repository root, and run the command again. If init has not run in this repository, run it there first:

npx @athenode/cli init

"No Athenode setup is installed in this project. Run `athenode init` first."

The command changes the installed setup, and no setup is installed in this directory. An agent setup is a named bundle of what your AI coding tools work with: skills, agents, rules, MCP servers and setup files.

Run init in the repository root and confirm its plan. To change a setup that is not installed here, pass its id with --setup-id, as the Athenode CLI reference describes.

An error that starts "Authentication error"

The project token stored in .athenode/config.json is not accepted, or the member it belongs to may not make this change. A project token is a personal access token that lets the Athenode CLI, and your AI agent through it, act on one project.

In the web app, open Tokens and find the token. A token marked Expired has passed its expiry, and a token that is not listed was revoked.
If the token is expired or revoked, select New token, copy the token and run npx @athenode/cli init in the repository root. Answer yes to "Replace it?" and enter the token.
If the token is valid, check your role on the Users page. A token acts with the role of the member who created it. A viewer's access is read-only, and deleting a specification needs the owner role.

A token also stops working when its member is removed from the project. Project tokens covers expiry and revoking, and Roles and permissions lists what each role can do.

A command exits with code 3 and the error has `code: "plan_limit_exceeded"`

The change would take the project over a limit of its plan, and nothing was changed.

Read the fields limit, current and max of the error to see which limit was reached. Then remove something that counts towards that limit, or ask the project owner to move the project to a higher plan on the Plan & limits page. Plans and limits lists every limit per plan.

A message that starts "This version of @athenode/cli"

The copy of the Athenode CLI that ran is older than the version Athenode accepts, which happens with a copy installed globally or pinned in a script.

Run the CLI with npx @athenode/cli@latest, or update the installed copy:

npm i -g @athenode/cli@latest

Commands in a script pause and then fail

The script made more requests per minute than the project's plan allows. The limit is 60 requests per minute on Free, 300 on Solo, 600 on Team and 1,200 on Business, counted for the CLI and your AI agent together.

The CLI waits and retries up to 3 times before it fails with exit code 1. Space the commands out, or ask the project owner to move the project to a higher plan.

"no agent setup found with name" or "multiple agent setups found with name"

A setup is found by its exact name, and the name you passed matches no setup of the project or more than one.

Run npx @athenode/cli setups list, copy the id of the setup, and pass the id with the option the message names: --by-id or --setup-by-id.

Problems when you run `athenode init`

"No project token is stored in .athenode/config.json. Run `athenode init` in an interactive terminal to enter one."

The first init in a directory asks for the project token at a prompt, and this run could not ask because it used --yes or did not run in an interactive terminal.

Run npx @athenode/cli init once in a terminal on that machine and enter the token. Later runs with --yes, including runs in CI, reuse the stored token. With --dry-run the message ends differently and the fix is the same.

A message that starts "Error: invalid token"

The token you entered at the prompt of init was mistyped, cut off when pasted, revoked or expired.

In the web app, open Tokens, select New token and copy the token when it is shown. Athenode shows a token once. Run init again and paste it.

"Confirmation required but stdin is not a TTY. Re-run with --yes to apply the plan, or --dry-run to only print it."

init needs your answer to "Apply this plan?" and is not running in an interactive terminal, for example in CI or in a pipe.

Add --yes to apply the plan without the question, or --dry-run to print the plan and write nothing.

"Unknown agent id(s)" after `--targets`

One of the ids passed to --targets is not the id of a supported AI tool.

The message ends with the valid ids. Correct the list and run the command again. The supported AI tools page gives the id of each tool.

A rules file "has malformed athenode:rules marker comments"

Athenode keeps its rules in a block between the lines  and , and in the named file one of the two lines is missing, duplicated or out of order.

Open the file the message names, such as CLAUDE.md or AGENTS.md.
Delete every marker line and the Athenode rules they enclose. Keep your own content.
Run npx @athenode/cli init again. It writes the block afresh.

Edit the rules of a setup in the web app, because the content between the markers is replaced by every install. Rules in a setup explains the block.

"Cannot merge into unparsable file(s)"

A configuration file that init adds MCP servers or agents to exists and cannot be read as JSON, TOML or YAML.

The message names each file. Fix the syntax of the file, or move it away if you do not need it, and run init again. Nothing is written until every named file can be read.

The plan warns "locally edited, will be overwritten" or "locally edited, will be removed"

A skill or agent file that Athenode installed was edited in your repository after the last install, and the next install replaces or removes it.

To keep the edit, cancel the plan and make the same change in the setup: in the web app on the Setups page, or by asking /atn-manage in your AI tool. Then run init again. To discard the edit, confirm the plan. Install a setup explains which files Athenode replaces.

The plan warns "existing unmanaged server will be overwritten"

Your MCP configuration has a server of your own with the same name as an MCP server of the setup, and the install replaces yours.

Cancel the plan and rename one of the two: your server in the configuration file, or the setup's server in the web app. Then run init again. Servers with other names are kept.

The plan warns that "comments and formatting in it may be lost"

Athenode rewrites TOML and YAML configuration files when it changes them, such as .codex/config.toml or .poolside/settings.yaml, and the rewritten file keeps the settings without their comments and layout.

If the comments matter, cancel the plan, copy the file or commit it, and run init again. Your own settings in the file are kept either way. The files installed per tool say which files are rewritten.

The plan lists an agent or an MCP server under "Not installed:"

One of the selected AI tools cannot take that item, and the line gives the reason. The other tools get the item. The supported AI tools page lists what differs by tool.

Item and AI tool	What to do
An HTTP or SSE server for Goose	Goose takes local-command MCP servers. Use the server from another AI tool, or add a local-command server to the setup.
An agent with the same name as a skill, for Reasonix	Rename the agent or the skill in the setup.
An agent named `general` for Pool	Rename the agent in the setup, because Pool has an agent of that name.
A mode or agent of your own with the same name, for Zoo Code, IBM Bob or Pool	Rename or remove your entry in the file the line names, then run `init` again.

"Missing MCP environment variables (not set in this shell):"

An MCP server of the setup refers to an environment variable with ${VAR}, and that variable is not set in the shell where the CLI ran.

Set each listed variable in the environment your AI tool starts in. The CLI can only check its own environment, so the list may name a variable that your AI tool does have. MCP servers in a setup explains the references.

Installed files show up in `git status` although you chose `--gitignore`

The files were committed before they were listed in .gitignore, and git keeps tracking a file that is already in the repository.

Stop tracking them once, for example the Claude Code skills:

git rm -r --cached .claude/skills

Rules files and MCP configuration files are never listed in .gitignore, because they also hold your own content.

Problems in your AI tool after an install

The skills, agents or MCP servers of a setup do not appear

The AI tool loaded its configuration before the install, or the install was made for other AI tools.

Restart the AI tool, or reload its MCP servers.
Open the AI tool in the directory where you ran init.
Run npx @athenode/cli init again and check that the tool is selected in the list of AI tools.

A skill such as `/atn-mindmap` is not recognised as a slash command

The way to run a skill differs by AI tool. A skill is a reusable set of instructions that an AI tool loads when it is relevant, usually run as a slash command such as /atn-mindmap.

After an install, init prints how to run a skill in each selected tool. In a tool without slash commands for skills, ask the agent to use the skill by name. The supported AI tools page gives the form for every tool.

Athenode tools fail with "no .athenode/config.json found in"

The Athenode MCP server was started outside your repository and could not find the project directory.

Open your AI tool in the repository root, where init ran. If you need to open it elsewhere, set the environment variable ATHENODE_PROJECT_DIR to the repository root, or add --project-dir to the server's arguments. Athenode MCP server gives the order in which the server looks for the project.

An MCP server of the setup does not connect

The server needs an environment variable that is not set where your AI tool runs, so the ${VAR} reference in its configuration has no value.

Run npx @athenode/cli init --dry-run to see the list of missing variables. Set them in the environment your AI tool starts in and restart the tool.

Your AI agent cannot reopen, edit or delete a ToDo card

An agent can create a card, read cards, close an open card as done or dismissed, and answer a question that has no answer. A ToDo card is a short note of work to do later: a follow-up, tech debt, a bug or an idea.

Reopen, edit or delete the card in the web app on the ToDo page. ToDo cards describes each action.

A change made on the Setups page does not reach your AI tool

The web app changes the setup in your Athenode project, and the files in your repository change when the setup is installed again.

Run npx @athenode/cli init in the repository root, confirm the plan and restart your AI tool.

Plan limits and roles that stop an action

"Plan limit reached" in the web app

The action would take the project over a limit of its plan. The dialog shows the usage and the limit.

The owner sees a button that starts with Upgrade to and names the next plan. Other members see "Ask the project owner to upgrade the plan." On the Free plan a project holds 100 specifications, 100 ToDo cards and one setup with up to 10 skills, 15 agents and 3 MCP servers. Plans and limits has the limits of every plan.

`library add` or `setups clone` exits with code 3 on the Free plan

On the Free plan a project holds one setup, which is your project's copy of the standard Athenode setup.

Merge the library entry into that setup with library merge. Adding an entry as a setup of its own and cloning a setup are possible on the Solo, Team and Business plans.

`library publish` exits with code 3

Publishing to the setup library needs the Solo, Team or Business plan, and the project is on the Free plan. The setup library is the shared catalogue of agent setups that projects have published.

Ask the project owner to change the plan, then publish again. Publish a setup lists the other requirements.

You cannot create another project token

The project's plan sets how many project tokens each member has in a project: 1 on Free, 10 on Solo and Team, 20 on Business.

On the Tokens page, select Revoke on a token you do not use, then create the one you need. On the Free plan a member has one token per project, so a second one needs a higher plan.

You are a viewer and cannot connect the CLI

A viewer cannot create a project token, so a viewer cannot connect the CLI or an AI agent to the project.

Ask the project owner to change your role to editor on the Users page. An editor or the owner can connect the CLI.

"Inviting members requires the Team plan or higher."

The Free and Solo plans have one member, the owner. The Team plan has up to 10 members and the Business plan up to 50, and pending invites count.

The owner changes the plan on the Plan & limits page and sends the invite again. Invite and manage members describes invites.

"To create another project, delete one of your free projects or have one moved to a paid plan."

You own three projects on the Free plan, which is the most one person can own.

Delete a free project you do not need, or move one of them to a paid plan. Projects on a paid plan and projects you were invited to do not count.

Specifications, blockers and the setup library

Deleting a specification is refused and the error lists other specifications

Other specifications are blocked by the one you are deleting or by one of its sub-specifications. A blocker is a dependency between two specifications: a specification that is blocked by another is implemented after it.

Remove those blockers first with specs blockers remove, or pass --force to delete anyway. Deleting a specification also needs a project token of the owner.

A blocker is refused

A specification cannot be blocked by itself, by one of its ancestors or sub-specifications, by a specification that is completed, by a specification of another project, or by a specification that already blocks it. A link that would close a cycle is refused too.

Choose a blocker that is none of these. When you add several blockers at once and one is refused, none is added, so remove the refused id and run the command again.

`specs create --todo-card` is refused

The ToDo card already became a specification, and a card is linked to one specification.

Run npx @athenode/cli todos get <card-id> to see the specification the card became, and continue with that specification.

A pull, merge or update is refused after a preview

The setup, the library entry or the source setup changed between the preview and the command, and nothing was written.

Run the preview command again, build your decisions from the fresh result and repeat the command.

Publishing is refused because of an MCP server value

An MCP server of the setup holds a literal environment variable or header value, and a published setup may only hold ${VAR} references there.

Replace each literal value with a ${VAR} reference in the setup, set the variable in the environment your AI tool starts in, and publish again. MCP servers in a setup describes the references.

`library add` is refused because the name is taken

The project already has a setup with the name of the entry.

Pass another name with --name. The error suggests a name that is free.

Last updated: 2026-10-08