Troubleshooting

error: not logged in — run parsemend login first.

Every command except login, logout and upgrade needs the token in ~/.parsemend/config.json. This is also what an MCP client will surface if the server starts and immediately dies: parsemend mcp refuses to serve without a token.

Commands worked yesterday, now everything returns 401

The token was revoked — by parsemend logout on this machine, or by the same account signing out elsewhere. The CLI makes no validation call of its own, so a dead token first shows up as a failed request rather than at startup. Run parsemend login again.

this login request expired

A login request lives 15 minutes from the moment parsemend login prints the code. Run it again for a fresh one. The same message covers a device code the server does not recognise, on purpose — an unknown code and an expired one get the same answer rather than confirming which codes once existed.

The session shows no Parsemend tools

In Claude Code, /mcp lists connected servers. If parsemend is missing or shows zero tools, work through:

1. parsemend --version in a terminal. If that fails, the package is not installed globally, or npm's global bin is not on your PATH.
2. Restart the client. Most MCP clients read their server list at startup.
3. Confirm the client can see the same PATH you can. A GUI client launched from the dock does not inherit a PATH your shell profile sets, which is the usual cause of "works in my terminal, not in the app". Point the client at the absolute path from which parsemend if so.
4. Check the server can start: parsemend mcp in a terminal should print parsemend mcp: serving <directory> to stderr and then sit there waiting for protocol frames. Ctrl-C to exit.

The tools read the wrong repository

analyze_issue and post_back work in the directory the session launched in. Pin it when that is not what you want:

claude mcp add parsemend -- parsemend mcp --cwd /path/to/repo

list_issues and get_issue_context are unaffected — they talk to Parsemend, not to your checkout.

post_back says there is nothing to publish

It reads git diff HEAD, which sees staged and unstaged changes only:

• The work is already committed. The diff against HEAD is empty. Publish before committing.
• The change is a new file. Untracked files are invisible to git diff. git add it and try again.
• Neither, and no analysis has run. Then there is genuinely nothing to file, and it declines rather than creating an empty run.

postlyra-12 is not an issue id

Three forms are accepted: the <project-slug>-<number> id that parsemend issues prints, the numeric id, and a full issue URL. The check happens locally, before any request, so this is a typo rather than a missing issue.

Pointing at a self-hosted deployment does nothing

PARSEMEND_API_URL is read from the process environment. An MCP client launches parsemend as a subprocess, so it inherits the client's environment, not your shell's. Set it in the client's own env block for that server, not in .zshrc.

analyze_issue fails with a provider error

That tool is the one path that spends your own model tokens, resolved from ANTHROPIC_API_KEY, OPENAI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY depending on the configured provider. The same subprocess-environment rule applies: the key has to be visible to the process the client launched.

If you did not mean to spend a key, use get_issue_context instead and let the session reason about the bundle itself.

When the message is all you get

There is no --verbose and no debug flag. Failures print one line — error: <message> — and exit 1. What you can do instead: run the equivalent command in a terminal, where the same code path prints the same message without an MCP client in between, and check the client's own MCP log for the server's stderr.