Solución de problemas

Esta página cubre fallos reales y documentados, no una lista genérica. Cada punto nombra la causa real y su arreglo.

La compilación del PDF falla o se queda colgada descargando paquetes

Síntoma: el PDF nunca termina de compilar, o se detiene a mitad de camino sin ningún progreso visible.

El motor de PDF por defecto de ComdTeX es una compilación WebAssembly del motor SwiftLaTeX, así que no necesita una instalación de LaTeX en el sistema para la mayoría de los documentos. Para compilar, descarga bajo demanda cualquier .sty, .cls o fuente que no traiga incorporado desde un servidor público de paquetes TeX (https://texlive2.swiftlatex.com/ por defecto). Ese servidor es un recurso comunitario con historial documentado de caídas, y cuando está caído, la compilación se queda esperándolo.

Dos arreglos independientes:

Apunta Configuración → PDF → Servidor de paquetes TeX a un espejo. Es la opción que lee el motor WASM para los archivos que le faltan.
Instala un motor local: tectonic, xelatex o pdflatex. La cadena de reserva de ComdTeX es WASM SwiftLaTeX, luego tectonic, luego xelatex, luego pdflatex; gana el primero que tenga éxito. Si el WASM está apagado o no está disponible, ComdTeX cae automáticamente al motor local que tengas instalado, sin ningún paso extra de tu parte.

Exportar a DOCX, Beamer o Typst, o importar un documento, no hace nada

Síntoma: al pulsar un botón de exportar o importar no pasa nada, o la entrada de menú directamente no aparece.

Estas funciones ejecutan herramientas de línea de comandos que ComdTeX no incluye:

Función	Necesita
Exportar a DOCX, exportar a Beamer, Markdown a PDF (ruta sin LaTeX), importar documento (docx/odt/tex/html/epub/rst/org)	`pandoc`
Exportar a Typst (`.typ`)	`pandoc`
Compilar un archivo Typst a PDF (ya sea un `.typ` nativo o uno exportado con pandoc)	`typst`, además de `pandoc` para el paso de exportación
Copia de seguridad del vault / archivo `.cmdx`	`zip`
El panel de Git	`git`

La exportación a PDF simple no necesita nada de esto: el motor WASM incorporado la maneja por su cuenta.

ComdTeX verifica si tienes pandoc, zip y typst al iniciar. Cuando falta pandoc o zip, muestra un banner ámbar que nombra la herramienta y para qué se necesita, con un enlace de instalación y un botón para descartarlo por herramienta. Si falta typst, no aparece ese banner: en su lugar, la entrada de menú para compilar Typst a PDF simplemente no aparece. Si falta git tampoco se verifica al iniciar: el panel de Git dice “git no está instalado” cuando lo usas, y lo distingue de “esta carpeta no es un repositorio” y de cualquier otro error de Git, que muestra tal como lo informó.

Falta algo en una exportación o salió incompleta

ComdTeX muestra un aviso corto antes de exportar con las funciones que el formato de destino no puede conservar (la exportación sigue adelante). Si algo falta en un archivo DOCX, Beamer o Typst, revisa primero ese aviso: es un límite del formato, no un fallo.

El AppImage no arranca: `libfuse.so.2`

Al ejecutar el AppImage sale dlopen(): error loading libfuse.so.2 y “AppImages require FUSE to run”, y el lanzador no hace nada. Un AppImage montado necesita FUSE 2, que las distros recientes ya no instalan por defecto (entre ellas Ubuntu 24.04 y Arch). Instálalo una vez:

sudo apt install libfuse2t64   # Ubuntu 24.04 en adelante (libfuse2 en versiones anteriores)
sudo dnf install fuse-libs     # Fedora
sudo pacman -S fuse2           # Arch, Manjaro

Sin permisos de root, APPIMAGE_EXTRACT_AND_RUN=1 comdtex lo abre igual descomprimiéndolo en cada arranque, que es más lento. Desde la 1.32.0 el instalador de una línea avisa cuando falta FUSE 2.

ComdTeX dejó de abrir después de actualizar desde la app en Arch

Antes de la 1.32.0, Instalar en el aviso de actualización reemplazaba la copia descomprimida y parcheada que el instalador de una línea deja en las distros basadas en Arch por un AppImage sin parchear. El resultado necesita FUSE 2 (ver arriba) y pierde el parche de libwayland del instalador, así que también puede abrir como una ventana en blanco. Vuelve a correr el instalador de una línea (ver Instalación): repone la copia parcheada, y desde la 1.32.0 el aviso en estas instalaciones copia ese comando en vez de instalar.

El AppImage no compila en Arch y otras distros Linux modernas

Esto aplica si estás compilando ComdTeX desde el código fuente, no al AppImage que descargas de una release.

La herramienta linuxdeploy incluida trae un strip antiguo que no soporta la sección ELF .relr.dyn que producen las cadenas de herramientas modernas, así que falla con strip: unknown type [0x13]. Compila con el strip desactivado:

NO_STRIP=true npm run tauri build -- --bundles appimage

El paso del AppImage también puede fallar de forma pasajera con failed to run linuxdeploy, incluso con NO_STRIP=true puesto. Reintenta el mismo comando una vez antes de investigar más; se ha visto que funciona en el siguiente intento sin ningún otro cambio. El binario, el .deb y el .rpm compilan sin problemas de todas formas y ya son usables en ese punto.

Los archivos o imágenes no cargan después de abrir un vault

Síntoma: el árbol de archivos o la vista previa no pueden leer archivos dentro de un vault que acabas de abrir.

ComdTeX no da acceso al sistema de archivos sobre toda tu carpeta personal. Cada directorio de vault se autoriza en tiempo de ejecución, en el momento en que lo abres. Si ese paso de autorización no se ejecuta, el acceso a archivos e imágenes dentro del vault se rompe. No hay ninguna opción de configuración para arreglar esto por tu cuenta: si te pasa, vale la pena reportarlo como un fallo en vez de buscarle la vuelta, porque apunta al propio paso de apertura del vault y no a nada que hayas configurado.

Los conflictos de Google Drive son invisibles

Síntoma: dos máquinas editaron el mismo archivo a través de Google Drive, y ComdTeX no muestra ningún aviso de conflicto, aunque se perdió una edición.

ComdTeX detecta los archivos de copia en conflicto que dejan Dropbox y OneDrive cuando no pueden fusionar dos versiones de un archivo (el nombre (conflicted copy AAAA-MM-DD).ext de Dropbox, los nombres con sufijo de dispositivo de OneDrive). Google Drive para escritorio no funciona así: sobrescribe en silencio, sin dejar ningún archivo marcador, así que no hay nada que ComdTeX pueda detectar. Esto es una limitación del propio comportamiento de sincronización de Google Drive, no un hueco en la lógica de detección de ComdTeX.

El arreglo confiable es dejar de depender de una sincronización de archivos silenciosa para lo que escribes con alguien más, y usar git en su lugar, que se detiene y pregunta cuando dos personas cambiaron las mismas líneas en vez de elegir un ganador en silencio. Ver Escribir con alguien más para hacer eso sin necesitar saber git de entrada.

La clave de API de IA no se recuerda entre sesiones

Síntoma: pegas una clave de API de un proveedor, funciona, y luego desaparece la próxima vez que abres ComdTeX.

La clave se guarda en el llavero del sistema operativo (Secret Service en Linux, Keychain en macOS, Credential Manager en Windows), aparte del resto de tus ajustes. No todas las instalaciones de Linux tienen un proveedor de Secret Service disponible, por ejemplo una instalación mínima de gestor de ventanas sin gnome-keyring ni kwallet. Cuando el llavero no está disponible, ComdTeX cae automáticamente a guardar la clave en el almacenamiento local de la app, así que el asistente sigue funcionando; solo la protección a nivel de sistema operativo queda fuera. Si tu clave sigue sin persistir aún después de eso, apunta a algo que está fallando al escribir en el almacenamiento local, y vale la pena reportarlo directamente.

Las peticiones de IA fallan

Síntoma: enviar un mensaje en el panel de IA, o pulsar Probar conexión en Configuración, devuelve un error.

El botón Probar conexión en Configuración envía la petición real más pequeña posible a tu proveedor configurado y nombra qué está mal. La página del asistente de IA documenta los cuatro resultados posibles y qué significa cada uno; ver El asistente de IA para esa tabla en vez de duplicarla aquí.

Troubleshooting

This page covers real, documented failure modes, not a generic checklist. Each item names the actual cause and the fix.

PDF compilation fails or hangs downloading packages

Symptom: the PDF never finishes compiling, or it stalls partway with no visible progress.

ComdTeX’s default PDF engine is a bundled WebAssembly build of the SwiftLaTeX engine, so it needs no system LaTeX installation for most documents. To compile, it lazy-fetches any .sty, .cls, or font file it does not already ship with from a public TeX package server (https://texlive2.swiftlatex.com/ by default). That server is a community resource with a documented history of outages, and when it is down, the compile hangs waiting on it.

Two independent fixes:

Point Settings → PDF → TeX package server at a mirror. This is the setting the WASM engine reads for missing files.
Install a local engine: tectonic, xelatex, or pdflatex. ComdTeX’s fallback chain is WASM SwiftLaTeX, then tectonic, then xelatex, then pdflatex; the first one that succeeds wins. If WASM is turned off or unavailable, ComdTeX falls back to whichever local engine is installed automatically, with no extra step from you.

DOCX, Beamer, or Typst export, or document import, does nothing

Symptom: pressing an export or import button produces nothing, or the menu entry for it is missing entirely.

These features shell out to command-line tools ComdTeX does not bundle:

Feature	Needs
DOCX export, Beamer export, Markdown to PDF (non-LaTeX path), document import (docx/odt/tex/html/epub/rst/org)	`pandoc`
Export to Typst (`.typ`)	`pandoc`
Compiling a Typst file to PDF (either a native `.typ` file or a pandoc-exported one)	`typst`, in addition to `pandoc` for the export step
Vault backup / `.cmdx` archive	`zip`
The Git panel	`git`

Plain PDF export does not need any of this: the bundled WASM engine handles it on its own.

ComdTeX checks for pandoc, zip, and typst on startup. When pandoc or zip is missing, it shows an amber banner naming the tool and what it is needed for, with an install link and a per-tool dismiss button. A missing typst does not raise that banner: instead, the Typst-to-PDF menu entry simply does not appear. A missing git is not checked at startup either: the Git panel says “git is not installed” when you use it, and tells that apart from “this folder is not a repository” and from any other Git error, which it shows as reported.

An export is missing or incomplete

ComdTeX shows a short notice before exporting that lists the features the target format cannot keep (the export still goes ahead). If something is missing from a DOCX, Beamer or Typst file, check that notice first: it is a limit of the format, not a failure.

The AppImage does not start: `libfuse.so.2`

Running the AppImage prints dlopen(): error loading libfuse.so.2 and “AppImages require FUSE to run”, and the launcher entry does nothing. A mounted AppImage needs FUSE 2, which newer distros no longer install by default (Ubuntu 24.04 and Arch among them). Install it once:

sudo apt install libfuse2t64   # Ubuntu 24.04 and later (libfuse2 on older releases)
sudo dnf install fuse-libs     # Fedora
sudo pacman -S fuse2           # Arch, Manjaro

Without root, APPIMAGE_EXTRACT_AND_RUN=1 comdtex starts it anyway by unpacking it on every launch, which is slower. Since 1.32.0 the one-line installer warns when FUSE 2 is missing.

ComdTeX stopped opening after an in-app update on Arch

Before 1.32.0, Install in the update banner replaced the unpacked, patched copy that the one-line installer sets up on Arch-based distros with a raw AppImage. The result needs FUSE 2 (see above) and loses the installer’s libwayland patch, so it may also open as a blank white window. Run the one-line installer again (see Installation): it puts the patched copy back, and from 1.32.0 on the banner on these installs copies that command instead of installing.

The AppImage does not build on Arch and other modern Linux distros

This applies if you are building ComdTeX from source, not to the AppImage you download from a release.

The bundled linuxdeploy tool ships an old strip that cannot handle the .relr.dyn ELF section modern toolchains produce, so it fails with strip: unknown type [0x13]. Build with stripping disabled:

NO_STRIP=true npm run tauri build -- --bundles appimage

The AppImage step can also fail transiently with failed to run linuxdeploy, even with NO_STRIP=true set. Retry the same command once before investigating further; it has been observed to succeed on the next run with no other change. The plain binary, the .deb, and the .rpm build cleanly regardless and are already usable at that point.

Files or images do not load after opening a vault

Symptom: the file tree or preview cannot read files inside a vault you just opened.

ComdTeX does not grant filesystem access to an entire home directory. Each vault directory is authorized at runtime, the moment you open it. If that authorization step does not run, file and image access inside the vault breaks. There is no user-side setting to fix this: if you hit it, it is worth reporting as a bug rather than something to work around, since it points at the vault-opening step itself rather than anything you configured.

Google Drive conflicts are invisible

Symptom: two machines edited the same file through Google Drive, and ComdTeX shows no conflict warning at all, even though one edit was lost.

ComdTeX detects the conflict-copy files that Dropbox and OneDrive leave behind when they cannot merge two versions of a file (Dropbox’s name (conflicted copy YYYY-MM-DD).ext, OneDrive’s device-suffixed filenames). Google Drive for Desktop does not work that way: it overwrites silently, with no marker file left behind, so there is nothing for ComdTeX to detect. This is a limitation of Google Drive’s own sync behavior, not a gap in ComdTeX’s detection logic.

The reliable fix is to stop depending on silent file sync for anything you write with someone else, and use git instead, which stops and asks when two people changed the same lines rather than picking a winner silently. See Write with someone else for doing that without needing to know git upfront.

The AI API key is not remembered between sessions

Symptom: you paste a provider API key, it works, and then it is gone the next time you open ComdTeX.

The key is stored in the operating system’s keychain (Secret Service on Linux, Keychain on macOS, Credential Manager on Windows), separate from the rest of your settings. Not every Linux setup has a Secret Service provider available, for example a minimal window-manager install without gnome-keyring or kwallet. When the keychain is unreachable, ComdTeX automatically falls back to storing the key in local app storage instead, so the assistant keeps working; it is only the OS-level protection that is unavailable. If your key still does not persist even after that, it points at something failing to write to local storage, worth reporting directly.

AI requests fail

Symptom: sending a message in the AI panel, or pressing Test connection in Settings, returns an error.

The Test connection button in Settings sends the smallest possible real request to your configured provider and names what is wrong. The AI assistant page documents the four possible results and what each one means; see The AI assistant for that table rather than duplicating it here.