# Troubleshooting Fixes for what can go wrong between your agent, the Entz connector and your documents, from tools that do not appear to links that do not open and edits that do not arrive. 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](/docs/mcp/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](/docs/mcp/connect/). - **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`: ```sh 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](/docs/mcp/connect/#environment-variables)) 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](/docs/apps/)), 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](#access-is-refused) and [Refusals](/docs/mcp/refusals/#errors-from-entz). ## 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](/docs/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](/docs/mcp/connect/#who-the-agent-is-in-entz) 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.