Wiki.js Plugin: Troubleshooting
Troubleshooting the Wiki.js plugin: server does not start, credentials missing, HTTP and GraphQL errors, page becomes a draft, shrink guard, truncated content, missing history.
Wiki.js Plugin: Troubleshooting
This documentation always describes the latest published version.
Server does not start or is not connected
Symptom: /mcp does not show wikijs-mcp as connected, or the wikijs_* tools are missing.
Check: Does ~/.wikijs-plugin/venv/ exist? The wrapper bin/run-server starts exactly that interpreter.
Solution: Run /wikijs-plugin:setup and restart Claude Code. If the skill reports MCP: MISSING, the exact import error is in the report. Re-syncing the dependencies and Python 3.11 or newer usually help.
Credentials missing
Symptom: Message Missing required environment variables WIKIJS_API_URL / WIKIJS_API_TOKEN. Set them in <path>/.env (see .env.example). The server exits at startup.
Solution: Set both variables in ~/.wikijs-plugin/.env and restart Claude Code. Changes to the file only take effect after a restart.
Connection and HTTP errors
| Message | Cause | Solution |
|---|---|---|
Wiki.js API request failed: ... |
Host not reachable, DNS or TLS problem | Check WIKIJS_API_URL, it must end with /graphql |
Request timed out. Please try again. |
No response within 30 seconds | Check network and Wiki.js load, try again |
HTTP error! status: 404 |
Wrong endpoint | Check the URL, it must end with /graphql |
HTTP error! status: 401 or 403 |
Token invalid or expired | Check the token in Wiki.js or generate a new one |
GraphQL request failed: ... |
Wiki.js rejected the request, e.g. because of a missing permission | The message names the reason. Check the token permissions (read:pages, write:pages, manage:pages) |
A page is a draft after the update
Cause: The update ran without isPublished. The tool does not take the status over from the page.
Solution: Call wikijs_update_page again with isPublished: true. That is a metadata-only update, content and tags are kept.
Update refused: content too short
Symptom: Refusing update: new content (... chars) is less than 50% of the current page's content (... chars). ...
Cause: The shrink guard detected a probably accidental partial overwrite, for example because only a fragment was sent.
Solution: Check that you send the complete text. If the reduction is intended, repeat the call with confirmContentShrink: true.
Page not found
Symptom: Page not found at path: ... or Page not found with ID: ...
Check: Path without leading slash, correct locale? The default is en, for German pages you must pass de.
Path is rejected
Symptom: Path must contain only alphanumeric characters, hyphens, underscores, and forward slashes
Cause: Paths with a dot, spaces or special characters are not allowed. .. and // are forbidden as well.
Solution: Address the page by id (wikijs_list_pages or wikijs_search_pages returns it).
Description is rejected on save
Symptom: Wiki.js reports a database error such as Data too long for column 'description'.
Cause: The tool allows up to 500 characters, the Wiki.js database limits to 255 in practice.
Solution: Shorten the description to at most 250 characters.
Page looks truncated
Symptom: The end of the content reads [Content truncated. Original length: ... chars. ...].
Cause: wikijs_get_page truncates from 100,000 characters. An update without its own content would write the truncated version back.
Solution: Do not edit such pages through wikijs_update_page.
History or verified markers are missing
| Observation | Cause |
|---|---|
wikijs_get_page_history returns nothing |
The write calls ran without sourceRepo, sourceRef and summary, or the path differs (e.g. after a move) |
wikijs_get_verified_refs is empty |
The page was never marked with wikijs_mark_verified, even if a written ref exists |
| Marker exists, the skill still checks everything | page_updated_at differs from the live updatedAt, the page was changed after the check |
| Everything unverified on a second machine | The database is local, there is no synchronisation |
Message page-history logging failed in the server log |
Database locked or not writable. The Wiki.js page was written anyway |
Tools appear twice
Besides this plugin, the Node.js server wikijs-mcp-server is still registered manually. Remove the old registration.