Deutsche Version

Back to overview

Troubleshooting

The server writes diagnostic messages to stderr. Where you find this output depends on your MCP client.

Server does not start: missing variables

Message: Error: Missing required environment variables and Please ensure WIKIJS_API_URL and WIKIJS_API_TOKEN are set in .env file

Cause: WIKIJS_API_URL or WIKIJS_API_TOKEN is not set, or the server did not find the .env.

Solution:

1. Check whether ~/.claude/mcp-servers/wikijs/.env exists. If so, only that file is read and a .env in the repository is ignored.
2. If that file does not exist, the server reads the .env from the working directory of the process. That is often not the repository.
3. When in doubt, set the variables directly in your MCP client configuration.

Details: Configuration.

Server does not show up as connected

• Did you run npm run build? Without dist/index.js the client cannot start anything.
• Is the absolute path to dist/index.js in the client configuration correct?
• Is node available in the client process (PATH) and version 18 or newer?
• Did you fully restart the MCP client after changes?

HTTP errors

Message: Wiki.js API request failed: HTTP error! status: <code>

GraphQL errors

Message: Wiki.js API request failed: GraphQL request failed: <message>

The text comes from Wiki.js. A message such as Forbidden indicates that the API key lacks a required permission. .env.example lists read:pages, write:pages and manage:pages. The complete error list is also written to stderr.

Operation rejected

Message: Failed to create page: ..., Failed to update page: ..., Failed to delete page: ... or Failed to move page: ...

Wiki.js understood the request but rejected it. Typical cases: the page already exists at that path (create), the destination path is taken (move) or the key lacks a permission. The text after the colon comes from Wiki.js.

Page not found

Message: Page not found at path: <path> or Page not found with ID: <ID>

Check the path and above all locale: the default is en. A German page is only found with locale: "de".

Validation errors

Message: Validation error in <tool>: with a list of field and reason.

Common causes:

• path with a dot, umlaut, leading slash or //: allowed are letters, digits, -, _ and /
• locale in the wrong format, expected e.g. de or en-US
• content empty or over 500,000 characters, title over 200 or description over 500 characters
• more than 50 tags or a tag over 100 characters
• neither id nor path given: Either "id" or "path" must be provided

Timeout

Message: Request timed out. Please try again.

Wiki.js did not answer within 30 seconds. Check that the instance is reachable. On very large wikis wikijs_list_pages can be slow because the complete page list is loaded every time; this also applies to wikijs_update_page without tags.

Content looks cut off

Pages over 100,000 characters are truncated on read, recognisable by the [Content truncated. ...] notice at the end. Do not write this text back, see the warning under wikijs_update_page in the Tools reference.

Page became a draft after an update

If isPublished was not passed on the update, Wiki.js may treat the page as unpublished. Set the page back to published with an update and isPublished: true.