Troubleshooting

Most problems show up in one of two places: your client’s list of servers, which says whether the connector started, and the tool results in your conversation, where a refused call names its code. Refusals explains every code.

The tools do not appear

• Check the list of servers. Claude Code, Codex and Gemini CLI list their servers with /mcp, and VS Code with MCP: List Servers in the Command Palette. entz shows there as connected or as failed.
• Claude Code. A server added during a session may not appear until the next one: start a new session, then run /mcp. A failed server can be reconnected from there.
• Clients that read a configuration file. Many start their servers only when they launch: quit the client completely and open it again. A missing comma or bracket in the file can stop every server in it, so check it against the examples in Connect an agent.
• See the error for yourself. Run npx -y entz-mcp in a terminal. When all is well it prints nothing and waits, since it talks to its client over standard input; press Ctrl+C to stop it. An error printed there is the one your client runs into.

npx or Node.js problems

• Node.js too old. The connector needs Node.js 22.3 or later. With an older one it starts, but every call except guide and open fails with a message about WebSocket or fetch. Run node --version, and update Node.js if it is older.

• The client cannot find npx. An error such as spawn npx ENOENT means the client did not find npx on its path. This can happen when Node.js comes from a version manager and the client was started from the Dock or the Start menu. Use the full path to npx as the command: which npx prints it on macOS and Linux, where npx on Windows.

• Windows and Claude Code. When /mcp shows entz as failed on Windows, remove it and add it again through cmd /c:

  claude mcp remove entz
  claude mcp add entz -- cmd /c npx -y entz-mcp

• A slow first start. The first start downloads the connector and its dependencies, some tens of megabytes, and a client may stop waiting before that is done. Run npx -y entz-mcp once in a terminal so the download is kept, stop it when it sits waiting, then restart the client.

The agent shows as Claude

The connector names the agent Claude unless ENTZ_AGENT_NAME says otherwise, whichever agent is behind it. Set that variable to your agent’s name (Connect an agent) and restart the connector.

The browser does not open

When create or open does not open your browser, its answer says opened: false and the agent gives you the link instead.

• ENTZ_OPEN is 0. That setting keeps the browser closed on purpose.
• The connector runs elsewhere. On a remote machine, in a container or over SSH, the connector has no browser of yours to open, or opens one on the wrong machine. Set ENTZ_OPEN to 0 there, so that the agent always hands you the link to open on your own computer.
• Linux. The connector opens links with xdg-open. Without it, you get the link in the conversation instead.

A link does not open in Entz

• “Sign in to open this document”. A document you have not opened on this device before opens only when you are signed in to Entz, and that includes every document an agent creates. Sign in (Settings, Connection, Sign in), then open the document from your library, where it is waiting.
• “You do not have access to that document”. The document keeps to its members and you are not one. Its owner can turn on Anyone with the link under Access…, or add you by the email you signed in with. “That tab is not available” says the same of one tab.
• On a phone. Links from the connector are web links, so they open entz.app in the browser. To open the document in the iOS or Android app (Web, iOS and Android), use Open by id… in the New menu and paste the link without its ?tab= part.

Access is refused

• access. The agent cannot open the document: the owner has turned off Anyone with the link, or the link is wrong. Turning the link on, with Edit, lets the agent in.
• not-member. The agent opened the document, but the link let it in to view or to comment only, so its edits or comments are refused. Give the link the permission the agent needs under Access…, then restart the connector: members keep the permission they joined with, and a fresh start joins again with the new one. In Claude Code, reconnect entz from /mcp or start a new session; in other clients, restart the client.

Edits refused this way were applied to the connector’s own copy of the document, and nobody else saw them. After the restart, ask the agent to make them again.

The agent’s edits do not arrive

• synced: false. Entz did not confirm the write within 15 seconds, usually because the connection is slow or gone. The connector keeps the write and sends it once it is connected again, as long as it keeps running: it keeps nothing on disk, so a write not yet sent is lost if the connector stops first. Check the document in Entz, and ask the agent to write again what is missing.
• A refusal from Entz. not-member and too-large refuse the write on the server; see Access is refused and Refusals.

The agent wrote over my words

An agent’s edits cannot overwrite words that had already reached it: a whole-block change names the version it read and is refused if the block has changed since, and a change to a few words touches only words that still match its quote. The one way past this is force, which the connector’s instructions keep for when you ask the agent to overwrite something. When something you wrote changed all the same, one of these happened:

• you asked the agent to rewrite that part, or to overwrite it;
• your edit and the agent’s crossed: an edit made in the same instant, still on its way to the agent, meets its write as two people’s simultaneous edits meet;
• someone else in the document changed it.

History… in the document’s menu shows every version, and restores one as a copy (History).

The agent’s avatar or caret stays

An agent stays on a document or tab until 90 seconds after it last worked there, and moves as soon as it works somewhere else. When the connector stops, the agent leaves at once, or within about 15 seconds if the connector was stopped abruptly. If its caret stays longer than that, reload the page.

The agent’s words appear at once

Words fade in only for writes less than a minute old, comparing your computer’s clock with the clock of the machine the connector runs on: if the two differ by more than a minute, the agent’s words appear at once. Setting both clocks from the network fixes it. Text in table cells always appears at once, and so do the words of a write beyond its first 300.

Grey lines in brackets stay in the document

Those are placeholders for sections the agent has not written, because it was stopped or its call was refused. Ask the agent to fill the remaining sections, and it finds them in the outline; or select one and delete it. Placeholders are left out of Markdown, HTML, Typst and plain text exports.

The agent cannot find a document

The agent cannot see your library, and each time the connector starts, it is a new identity with no documents of its own. Give the agent the link: Copy link in the document’s menu.

A document the agent made is not mine

A document an agent created belongs to its identity, so you cannot change who its link admits or delete it for everyone; Delete takes it off your list only. Connect an agent explains why, and how to have a document of your own instead.

The agent reports rev_expired

Nothing is wrong. The connector forgets its revision numbers when it restarts, or when it closes a document it has left unused for 10 minutes. The agent reads the outline again and carries on from there.