Problemen oplossen¶

Het diagnostieklogboek van de editor bevat elke relevante regel. Op Windows staat het in %LOCALAPPDATA%/MTE/log/. Kijk naar het nieuwste bestand na het starten van de editor.

«Python plugins disabled»¶

Vier smaken; het precieze bericht zegt welke.

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

Neutraal — de host staat op het punt Python in het PATH te zoeken. Prima, tenzij er «no Python interpreter found» op volgt.

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

U hebt MTE_PYTHON op een pad met een mapscheiding gezet, maar het bestand op dat pad ontbreekt. Oplossing: wijs naar de echte python.exe.

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

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

U hebt MTE_PYTHON op een kale naam gezet (zonder scheiding), maar die naam staat niet in het PATH. Oplossing: voeg de map aan het PATH toe, of gebruik de vorm met het volledige pad hierboven.

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

Noch MTE_PYTHON, noch een van de standaardnamen van het platform (py.exe, python.exe, python3.exe op Windows; python3 op macOS/Linux) staat in het PATH. Installeer Python 3.9+ en voeg het aan het PATH toe of stel MTE_PYTHON in.

Kijk wat het PATH op dit moment ziet, vanuit dezelfde shell van waaruit u de editor gestart hebt:

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

«python worker script … not found»¶

De editor noteert:

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

Het hostscript van de worker (mte_python_host.py) staat niet naast het uitvoerbare bestand. Dat gebeurt bij het draaien van een editorbuild waarvan de POST_BUILD-stap die Python/ klaarzet is overgeslagen. Bouw opnieuw:

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

Bevestig na het bouwen dat het bestand bestaat:

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

Plug-in opgesomd maar niet geladen¶

Open de pagina Plug-ins (Voorkeuren → Plug-ins). Veelvoorkomende oorzaken:

Symptoom	Regel in het logboek	Oorzaak
Etiket over een verschil in `apiVersion` naast de naam	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Uw `plugin.json` verklaart een andere `apiVersion` dan de draaiende editor ondersteunt.
De plug-in ziet er grijs uit	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Iemand heeft haar op de pagina Plug-ins uitgeschakeld. Schakel haar weer in en herstart.
Helemaal afwezig	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	De statische sonde heeft uw module afgewezen. Verplaats `register` naar het hoogste niveau (kolom 0).
Helemaal afwezig	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` is `"main"` maar er staat geen `main.py` naast.
Helemaal afwezig	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Voeg `id` toe.

De opdracht gaat niet af¶

U klikte het menu-item aan of drukte de sneltoets in, maar er gebeurde niets.

Kijk of er regels [python:<your.id>] … van uw ctx.log.info(...) staan. Ontbreken die, dan heeft de callback de worker nooit bereikt.
Kijk of er regels [worker stderr] … staan. Uitzonderingen binnen uw callback belanden daar.
Bevestig dat de opdracht-id in uw aanroep van add_item letterlijk overeenkomt met uw command(id=...) — het vergelijken van tekenreeksen is exact.

Fouten «worker died»¶

De host noteert:

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

Het Python-subproces is geëindigd. Kijk boven die regel naar de stderr van de worker — Python drukt tracebacks naar stderr af en de host stuurt die door als [worker stderr] …. Een crash komt vrijwel altijd overeen met een niet-opgevangen uitzondering in register() of in een callback die weer in de C-API van Python terechtkwam.

Herstel door de code te repareren en de editor te herstarten. De host herstart een gecrashte worker niet automatisch.

Het inrichten van het venv is mislukt (plug-in opgesomd maar niet geladen)¶

Een plug-in die pyRequires verklaart krijgt bij haar eerste start een virtuele omgeving ingericht. Mislukt dat, dan bevat het logboek de reden:

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 ...

Veelvoorkomende oorzaken: geen netwerk bij de eerste start, een verkeerd gespelde vereiste, een pakket zonder wheel voor de Python-versie van de gebruiker. Verhelp de oorzaak en herstart — het inrichten probeert het bij elke start opnieuw tot het lukt (het venv wordt pas aan het einde als compleet gestempeld). Om een schone herbouw af te dwingen verwijdert u <AppLocalData>/PluginVenv/<plugin-id>/. Machines zonder netwerk kunnen in plaats daarvan een vooraf gebouwd venv/ in het pakket meeleveren — zie Verpakken.

Het installatieprogramma weigerde mijn `.mteplugin`¶

Elke afwijzing komt met een specifiek venstertekst; de veelvoorkomende:

Het bericht zegt…	Oplossing
het verplichte veld `'module'` ontbreekt	Voeg `"module": "main"` toe aan `plugin.json`.
geen Python-module (.py-bestand)	Het archief heeft helemaal geen `.py` — hebt u de juiste map gecomprimeerd?
bevat de verklaarde Python-module `'X.py'` niet	`module` in `plugin.json` komt niet overeen met de bestandsnaam in het archief.
verklaart geen `def register(...)` op het hoogste niveau	Dezelfde regel als bij het vinden: `def register(` moet op kolom 0 van `<module>.py` beginnen.
mikt op API-versie N	Bouw opnieuw tegen de huidige `apiVersion` (zie plugin.json).
onveilig pad / te groot / te veel bestanden	Het archief heeft een veiligheidswaarborg laten afgaan — verpak het eenvoudig opnieuw (geen items met `..`, < 256 MiB uitgepakt).

Het pakket wordt tegen een tijdelijke kopie gevalideerd, dus een geweigerde installatie raakt een bestaande plug-in nooit aan.

Er wordt helemaal niets genoteerd¶

Bevestig dat uw afhandelaar werkelijk geïnstalleerd is. register(ctx) draait precies één keer per plug-in per start van de editor. Is register niet op het hoogste niveau van de module gedefinieerd, dan wijst de statische sonde de plug-in af voordat die ooit geladen wordt (zie «Plug-in opgesomd maar niet geladen» hierboven).

Voeg een startregel aan uw register toe:

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

Ziet u die niet in het logboek, dan voert de worker uw register niet uit — zoek in de eerdere regels van het logboek naar de reden.

Waar u daarna kijkt¶

Logboek aan de kant van de editor: %LOCALAPPDATA%/MTE/log/…
stderr van de worker: hetzelfde logboek, met het etiket [worker stderr]
Naslag: ctx-API, Gebeurtenissen, plugin.json
Ontwerpnotities: PYTHON_PLUGIN_ARCHITECTURE.md (wortel van het repository)