Solución de problemas¶

El registro de diagnóstico del editor recoge todas las líneas relevantes. En Windows está en %LOCALAPPDATA%/MTE/log/. Mira el archivo más reciente después de arrancar el editor.

«Python plugins disabled»¶

Hay cuatro variantes; el mensaje exacto te dice cuál.

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

Neutral: el anfitrión está a punto de buscar Python en el PATH. No pasa nada, salvo que a continuación venga «no Python interpreter found».

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

Pusiste en MTE_PYTHON una ruta con un separador de directorio, pero el archivo de esa ruta no existe. Solución: apunta al python.exe real.

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

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

Pusiste en MTE_PYTHON un nombre simple (sin separador), pero ese nombre no está en el PATH. Solución: o añades la carpeta al PATH, o usas la forma de ruta completa de arriba.

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

Ni MTE_PYTHON ni ninguno de los nombres estándar de la plataforma (py.exe, python.exe, python3.exe en Windows; python3 en macOS/Linux) están en el PATH. Instala Python 3.9 o superior y añádelo al PATH o define MTE_PYTHON.

Comprueba qué ve el PATH en este momento, desde el mismo intérprete de comandos desde el que lanzaste el editor:

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

«python worker script … not found»¶

El editor anota:

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

El script anfitrión del trabajador (mte_python_host.py) no está junto al ejecutable. Esto ocurre al ejecutar una compilación del editor en la que se saltó el paso POST_BUILD de preparación de Python/. Recompila:

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

Confirma que el archivo existe tras la compilación:

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

El plugin aparece listado pero no cargado¶

Abre la página de complementos (Preferencias → Complementos). Causas habituales:

Síntoma	Línea del registro	Causa
Etiqueta de discrepancia de `apiVersion` junto al nombre	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Tu `plugin.json` declara un `apiVersion` distinto del que admite el editor en ejecución.
El plugin aparece atenuado	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Alguien lo desactivó en la página de Plugins. Vuelve a activarlo y reinicia.
No aparece en absoluto	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	El sondeo estático rechazó tu módulo. Mueve `register` al nivel superior (columna 0).
No aparece en absoluto	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` es `"main"`, pero no hay ningún `main.py` a su lado.
No aparece en absoluto	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Añade `id`.

El comando no se dispara¶

Has hecho clic en el elemento de menú o has pulsado el atajo, pero no ha pasado nada.

Busca líneas [python:<your.id>] … procedentes de tu ctx.log.info(...). Si no están, la retrollamada nunca llegó al trabajador.
Busca líneas [worker stderr] …. Las excepciones dentro de tu retrollamada acaban ahí.
Confirma que el identificador de comando de tu llamada a add_item coincide literalmente con tu command(id=...): la comparación de cadenas es exacta.

Errores de «worker died»¶

El anfitrión anota:

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

El subproceso de Python ha terminado. Busca por encima de esa línea la salida de error del trabajador: Python imprime las trazas en stderr y el anfitrión las reenvía como [worker stderr] …. Un fallo casi siempre corresponde a una excepción no capturada en register() o en una retrollamada que volvió a entrar en la API de C de Python.

Recupérate arreglando el código y reiniciando el editor. El anfitrión no reinicia automáticamente un trabajador que ha fallado.

Falló el aprovisionamiento del entorno virtual (plugin listado pero no cargado)¶

Un plugin que declara pyRequires recibe un entorno virtual aprovisionado en su primer arranque. Cuando eso falla, el registro lleva el motivo:

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

Causas habituales: no hay red en el primer arranque, un requisito mal escrito, un paquete sin wheel para la versión de Python del usuario. Arregla la causa y reinicia: el aprovisionamiento se reintenta en cada arranque hasta que tiene éxito (el entorno virtual solo se sella como completo al final). Para forzar una reconstrucción limpia, borra <AppLocalData>/PluginVenv/<plugin-id>/. Las máquinas sin conexión pueden distribuir en su lugar un venv/ preconstruido dentro del paquete; consulta Empaquetado.

El instalador rechazó mi `.mteplugin`¶

Cada rechazo viene con un mensaje de diálogo concreto; los más habituales:

El mensaje dice…	Solución
falta el campo obligatorio `'module'`	Añade `"module": "main"` a `plugin.json`.
no hay ningún módulo de Python (archivo .py)	El archivo comprimido no tiene ningún `.py`: ¿comprimiste la carpeta correcta?
no contiene el módulo de Python declarado `'X.py'`	El `module` de `plugin.json` no coincide con el nombre de archivo del archivo comprimido.
no declara un `def register(...)` de nivel superior	La misma regla que en la detección: `def register(` debe empezar en la columna 0 de `<module>.py`.
apunta a la versión N de la API	Recompila contra el `apiVersion` actual (consulta plugin.json).
ruta insegura / demasiado grande / demasiados archivos	El archivo comprimido ha activado una salvaguarda de seguridad: vuelve a empaquetarlo de forma sencilla (sin entradas `..`, menos de 256 MiB descomprimido).

El paquete se valida contra una copia temporal, así que una instalación rechazada nunca toca un plugin existente.

No se registra nada en absoluto¶

Confirma que tu manejador está realmente instalado. register(ctx) se ejecuta exactamente una vez por plugin y por arranque del editor. Si register no está definido en el nivel superior del módulo, el sondeo estático rechaza el plugin antes de que llegue a cargarse (ver «El plugin aparece listado pero no cargado», arriba).

Añade una línea de arranque a tu register:

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

Si no la ves en el registro, el trabajador no está ejecutando tu register: revisa los registros anteriores para saber por qué.

Dónde mirar a continuación¶

Registro del lado del editor: %LOCALAPPDATA%/MTE/log/…
Salida de error del trabajador: el mismo registro, etiquetada como [worker stderr]
Referencia: API ctx, Eventos, plugin.json
Notas de diseño: PYTHON_PLUGIN_ARCHITECTURE.md (raíz del repositorio)