Wiki.js Plugin: Fehlerbehebung
Fehlerbehebung für das Wiki.js Plugin: Server startet nicht, Zugangsdaten fehlen, HTTP- und GraphQL-Fehler, Seite wird zum Entwurf, Schrumpf-Schutz, gekürzter Inhalt, Historie fehlt.
Wiki.js Plugin: Fehlerbehebung
Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Server startet nicht oder ist nicht verbunden
Symptom: /mcp zeigt wikijs-mcp nicht als verbunden, oder die wikijs_*-Tools fehlen.
Prüfung: Existiert ~/.wikijs-plugin/venv/? Der Wrapper bin/run-server startet genau diesen Interpreter.
Lösung: /wikijs-plugin:setup ausführen und Claude Code neu starten. Meldet der Skill MCP: MISSING, steht der genaue Importfehler im Bericht. Meist helfen die erneute Synchronisation der Abhängigkeiten und ein Python ab 3.11.
Zugangsdaten fehlen
Symptom: Meldung Missing required environment variables WIKIJS_API_URL / WIKIJS_API_TOKEN. Set them in <pfad>/.env (see .env.example). Der Server beendet sich beim Start.
Lösung: In ~/.wikijs-plugin/.env beide Variablen setzen und Claude Code neu starten. Änderungen an der Datei wirken erst nach einem Neustart.
Verbindungsfehler und HTTP-Fehler
| Meldung | Ursache | Lösung |
|---|---|---|
Wiki.js API request failed: ... |
Host nicht erreichbar, DNS- oder TLS-Problem | WIKIJS_API_URL prüfen, sie muss auf /graphql enden |
Request timed out. Please try again. |
Keine Antwort innerhalb von 30 Sekunden | Netz und Wiki.js-Last prüfen, erneut versuchen |
HTTP error! status: 404 |
Falscher Endpunkt | URL prüfen, sie muss auf /graphql enden |
HTTP error! status: 401 oder 403 |
Token ungültig oder abgelaufen | Token in Wiki.js prüfen oder neu erzeugen |
GraphQL request failed: ... |
Wiki.js hat die Anfrage abgelehnt, z. B. wegen fehlender Berechtigung | Die Meldung nennt den Grund. Rechte des Tokens prüfen (read:pages, write:pages, manage:pages) |
Eine Seite ist nach dem Update ein Entwurf
Ursache: Das Update lief ohne isPublished. Das Tool übernimmt den Status nicht aus der Seite.
Lösung: wikijs_update_page mit isPublished: true erneut aufrufen. Das ist ein reines Metadaten-Update, Inhalt und Tags bleiben erhalten.
Update abgelehnt: Inhalt zu kurz
Symptom: Refusing update: new content (... chars) is less than 50% of the current page's content (... chars). ...
Ursache: Der Schrumpf-Schutz hat einen vermutlich versehentlichen Teil-Überschreib erkannt, etwa weil nur ein Ausschnitt gesendet wurde.
Lösung: Prüfe, ob du den vollständigen Text sendest. Ist die Kürzung gewollt, wiederhole den Aufruf mit confirmContentShrink: true.
Seite nicht gefunden
Symptom: Page not found at path: ... oder Page not found with ID: ...
Prüfung: Pfad ohne führenden Slash, richtige locale? Der Standard ist en, bei deutschen Seiten muss de angegeben werden.
Pfad wird abgelehnt
Symptom: Path must contain only alphanumeric characters, hyphens, underscores, and forward slashes
Ursache: Pfade mit Punkt, Leerzeichen oder Sonderzeichen sind nicht erlaubt. Auch .. und // sind verboten.
Lösung: Seite per id ansprechen (wikijs_list_pages oder wikijs_search_pages liefert sie).
Beschreibung wird beim Speichern abgelehnt
Symptom: Wiki.js meldet einen Datenbankfehler wie Data too long for column 'description'.
Ursache: Das Tool erlaubt bis zu 500 Zeichen, die Wiki.js-Datenbank begrenzt in der Praxis auf 255.
Lösung: Beschreibung auf höchstens 250 Zeichen kürzen.
Seite wirkt gekürzt
Symptom: Am Ende des Inhalts steht [Content truncated. Original length: ... chars. ...].
Ursache: wikijs_get_page kürzt ab 100.000 Zeichen. Ein Update ohne eigenen content würde die gekürzte Fassung zurückschreiben.
Lösung: Solche Seiten nicht über wikijs_update_page bearbeiten.
Historie oder verified-Marker fehlen
| Beobachtung | Ursache |
|---|---|
wikijs_get_page_history liefert nichts |
Die Schreibaufrufe liefen ohne sourceRepo, sourceRef und summary, oder der Pfad weicht ab (z. B. nach einem Verschieben) |
wikijs_get_verified_refs ist leer |
Die Seite wurde nie mit wikijs_mark_verified markiert, auch wenn ein geschriebener Ref existiert |
| Marker vorhanden, Skill prüft trotzdem komplett | page_updated_at weicht vom Live-updatedAt ab, die Seite wurde nach der Prüfung geändert |
| Auf einem zweiten Rechner alles unverifiziert | Die Datenbank ist lokal, es gibt keine Synchronisation |
Meldung page-history logging failed im Server-Log |
Datenbank gesperrt oder nicht beschreibbar. Die Wiki.js-Seite wurde trotzdem geschrieben |
Tools erscheinen doppelt
Neben diesem Plugin ist noch der Node.js-Server wikijs-mcp-server manuell registriert. Entferne die alte Registrierung.