FAQ & troubleshooting

get_document returned "empty — or it never existed"

That is Rustpad, not the server: GET /api/text/{id} answers an empty string for an empty pad, a pad that never existed, and one that expired. The three cases are indistinguishable over the API. If you expected content, the pad has most likely expired — documents are dropped after 24 hours without an open connection and on every server restart, unless the instance runs with SQLITE_URI.

"the Rustpad WebSocket connection failed"

The HTTP endpoints worked but the socket did not (or vice versa) — almost always a reverse-proxy issue. The proxy in front of Rustpad must forward WebSocket upgrades on /api/socket/…. In nginx terms: proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";.

replace_in_document says the string occurs N times

By default the search string must match exactly once, so the model cannot accidentally rewrite more than it looked at. Either make the search string longer (include surrounding context) or pass replace_all: true deliberately.

Why did a dialog appear before set_document?

Replacing a non-empty pad destroys content that cannot be restored, so a person is asked first. replace_in_document asks too, but only when replace_all is about to change more than one place. For a single targeted change, and for append_to_document, nothing is asked — those are also the tools that play nicely with concurrent human edits.

A tool answered with a confirm_token instead of asking

That is the fallback for a client that cannot show a dialog. Call the tool again with the same arguments plus the token; it is single-use and lasts five minutes. See Asking a person for what it does and does not prove — and if your client can show dialogs, check whether ELICITATION is set to false somewhere in the environment. It is not prefixed, so it may have been meant for a different server.

Someone saw "rustpad-mcp" in their pad

Working as intended: while editing, the server announces itself as a collaborator named rustpad-mcp, so humans in the pad can see that a machine is typing. It disconnects as soon as the tool call finishes.

Can it list all pads?

No — Rustpad has no such API. Pads exist implicitly under every id; you have to know the ids you care about. get_stats tells you how many documents the server currently holds, but not their names.

Text with emoji ends up mangled

It should not — positions are counted in Unicode code points end to end, and the test suite covers astral characters explicitly. If you can reproduce a mangling, that is a bug: please open an issue with the exact before/after text.

One tool I expected is missing

Something narrowed the list. In order of likelihood:

• RUSTPAD_READ_ONLY is set, and it is a write tool.
• RUSTPAD_ALLOW_TOOLS is set and does not name it — it is an allow list, so anything not named is out.
• RUSTPAD_DENY_TOOLS names it, possibly through a prefix such as list_*.

A filtered tool is not registered at all, so it is missing from tools/list and answers tools/call with "tool not found". There is no state where it is hidden but still callable.

What it is not is a typo in one of those variables: an entry that matches no tool stops the server at startup and says which entry it was. See choosing the tools that load.