Fehlerbehebung¶

Das Diagnoseprotokoll des Editors enthält jede relevante Zeile. Unter Windows liegt es in %LOCALAPPDATA%/MTE/log/. Sehen Sie nach dem Start des Editors in die neueste Datei.

„Python plugins disabled“¶

Vier Varianten; die genaue Meldung sagt, welche.

`PluginHost: MTE_PYTHON is not set; falling back to PATH.`¶

Neutral — der Host sucht gleich Python im PATH. Unproblematisch, sofern nicht „no Python interpreter found“ folgt.

`PluginHost: MTE_PYTHON path '<value>' does not exist.`¶

Sie haben MTE_PYTHON auf einen Pfad mit Verzeichnistrenner gesetzt, aber die Datei dort fehlt. Lösung: auf die echte python.exe zeigen.

$env:MTE_PYTHON = "C:\Users\me\AppData\Local\Programs\Python\Python313\python.exe"

`PluginHost: MTE_PYTHON='<name>' not found on PATH.`¶

Sie haben MTE_PYTHON auf einen bloßen Namen (ohne Trenner) gesetzt, aber dieser Name ist nicht im PATH. Lösung: entweder den Ordner zum PATH hinzufügen oder die Vollpfad-Form oben verwenden.

`PluginHost: no Python interpreter found (…); Python plugins disabled.`¶

Weder MTE_PYTHON noch einer der plattformüblichen Namen (py.exe, python.exe, python3.exe unter Windows; python3 unter macOS/Linux) ist im PATH. Installieren Sie Python 3.9+ und fügen Sie es dem PATH hinzu oder setzen Sie MTE_PYTHON.

Prüfen Sie, was der PATH gerade sieht — aus derselben Shell, aus der Sie den Editor gestartet haben:

(Get-Command py.exe -ErrorAction SilentlyContinue).Source
(Get-Command python.exe -ErrorAction SilentlyContinue).Source

„python worker script … not found“¶

Der Editor protokolliert:

PluginHost: python worker script '<path>' not found; Python plugins disabled.

Das Worker-Host-Skript (mte_python_host.py) liegt nicht neben der Exe. Das passiert bei einem Editor-Build, dessen Python/-Staging (POST_BUILD-Schritt) übersprungen wurde. Neu bauen:

cmake --build Build\.cmake\x64-debug --target ModularTextEditor --config Debug

Nach dem Build bestätigen, dass die Datei existiert:

Test-Path Build\MTE_Windows_d\Python\host\mte_python_host.py

Plugin gelistet, aber nicht geladen¶

Öffnen Sie die Plugins-Seite (Einstellungen → Plugins). Häufige Ursachen:

Symptom	Zeile im Protokoll	Ursache
`apiVersion`-Konfliktmarke neben dem Namen	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Ihre `plugin.json` deklariert eine andere `apiVersion`, als der laufende Editor unterstützt.
Plugin erscheint ausgegraut	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Jemand hat es auf der Plugins-Seite deaktiviert. Wieder aktivieren und neu starten.
Fehlt ganz	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	Die statische Prüfung hat Ihr Modul abgelehnt. Verschieben Sie `register` auf die oberste Ebene (Spalte 0).
Fehlt ganz	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` ist `"main"`, aber daneben liegt keine `main.py`.
Fehlt ganz	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	`id` hinzufügen.

Befehl feuert nicht¶

Sie haben den Menüpunkt geklickt / das Kürzel gedrückt, aber nichts passierte.

Suchen Sie nach [python:<ihre.id>] …-Zeilen aus Ihren ctx.log.info(...). Fehlen sie, hat der Callback den Worker nie erreicht.
Suchen Sie nach [worker stderr] …-Zeilen. Ausnahmen in Ihrem Callback landen dort.
Bestätigen Sie, dass die Befehls-Id in Ihrem add_item-Aufruf Ihrem command(id=...) wörtlich entspricht — der Zeichenkettenvergleich ist exakt.

„worker died“-Fehler¶

Der Host protokolliert:

… worker exited with code N
… worker crashed (code N)

Der Python-Unterprozess hat geendet. Sehen Sie über dieser Zeile nach dem stderr des Workers — Python schreibt Tracebacks auf stderr, und der Host reicht sie als [worker stderr] … weiter. Ein Absturz entspricht fast immer einer unbehandelten Ausnahme in register() oder in einem Callback, der in Pythons C-API rekursiert ist.

Beheben Sie den Code und starten Sie den Editor neu. Der Host startet einen abgestürzten Worker nicht automatisch neu.

Venv-Provisionierung fehlgeschlagen (Plugin gelistet, aber nicht geladen)¶

Ein Plugin mit pyRequires bekommt beim ersten Start eine virtuelle Umgebung provisioniert. Schlägt das fehl, steht der Grund im Protokoll:

PluginHost: 'org.example.x' needs a venv (no venv provisioned yet).
PythonRuntime: provisioning venv at '...' (1 requirement(s)); ...
PluginHost: venv provisioning for 'org.example.x' failed: pip install
failed: ... No matching distribution found for no-such-package ...

Häufige Ursachen: kein Netz beim ersten Start, ein vertipptes Requirement, ein Paket ohne Wheel für die Python-Version des Nutzers. Ursache beheben und neu starten — die Provisionierung versucht es bei jedem Start erneut, bis sie gelingt (die venv wird erst am Ende als vollständig gestempelt). Für einen sauberen Neuaufbau <AppLocalData>/PluginVenv/<plugin-id>/ löschen. Offline-Maschinen können stattdessen eine vorgebaute venv/ im Paket mitliefern — siehe Paketierung.

Der Installer hat mein `.mteplugin` abgelehnt¶

Jede Ablehnung kommt mit einer konkreten Dialogmeldung; die häufigsten:

Die Meldung sagt…	Lösung
missing the required `'module'` field	`"module": "main"` zur `plugin.json` hinzufügen.
no Python module (.py file)	Das Archiv enthält gar keine `.py` — den richtigen Ordner gezippt?
does not contain the declared Python module `'X.py'`	`module` in `plugin.json` passt nicht zum Dateinamen im Archiv.
does not declare a top-level `def register(...)`	Dieselbe Regel wie bei der Erkennung: `def register(` muss in Spalte 0 von `<module>.py` beginnen.
targets API version N	Gegen die aktuelle `apiVersion` neu bauen (siehe plugin.json).
unsafe path / too large / too many files	Das Archiv hat eine Sicherheitsprüfung ausgelöst — schlicht neu packen (keine `..`-Einträge, < 256 MiB entpackt).

Das Paket wird gegen eine Arbeitskopie validiert, eine abgelehnte Installation rührt ein bestehendes Plugin also nie an.

Es wird gar nichts protokolliert¶

Bestätigen Sie, dass Ihr Handler wirklich installiert ist. register(ctx) läuft genau einmal pro Plugin und Editor-Start. Ist register nicht auf der obersten Modulebene definiert, lehnt die statische Prüfung das Plugin ab, bevor es je geladen wird (siehe „Plugin gelistet, aber nicht geladen“ oben).

Fügen Sie Ihrem register eine Startzeile hinzu:

def register(ctx):
    ctx.log.info("wordcount: register() ran")
    # …

Sehen Sie das nicht im Protokoll, führt der Worker Ihr register nicht aus — prüfen Sie die früheren Protokolle auf den Grund.

Wo weitersuchen¶

Editor-seitiges Protokoll: %LOCALAPPDATA%/MTE/log/…
Worker-stderr: dasselbe Protokoll, markiert [worker stderr]
Referenz: ctx-API, Ereignisse, plugin.json
Designnotizen: PYTHON_PLUGIN_ARCHITECTURE.md (Repo-Wurzel)