Cómo solucionar errores de conexión WebSocket de Moonraker en Printer Tools
Solución de problemas del WebSocket de Moonraker
La respuesta rápida
Printer Tools mantiene una conexión WebSocket activa con Moonraker en ws(s)://<host>/websocket y se reconecta automáticamente cada 5 segundos si se cae. La mayoría de los errores de conexión vienen de un host inaccesible, una dirección IP que cambió o Klippy que todavía no está listo, no de la propia aplicación. Comprobar esas tres cosas primero resuelve la mayoría de los casos.
Lo que necesitas
- La dirección IP local exacta o el nombre de host que usa actualmente la impresora que ejecuta Moonraker
- Confirmación de que Klippy muestra Ready y no Error o Shutdown
- La misma red accesible tanto desde el móvil o el ordenador como desde el host de la impresora
- La dirección completa, incluyendo esquema y puerto, si tu configuración usa HTTPS o un proxy inverso
- Cualquier API key de Moonraker, token Bearer o credenciales de Basic Auth que exija tu instalación
Diagnosticar un error de WebSocket de Moonraker
- 1
Confirma que Klippy está realmente listo
Abre el mismo host en un navegador o en Mainsail o Fluidd si los tienes instalados. Si Klippy también muestra Error o Shutdown ahí, el problema está en Klipper o en tu printer.cfg, no en Printer Tools, y reconectar la app no ayudará hasta que Klippy se recupere por sí mismo.
- 2
Vuelve a comprobar la dirección del host
Los routers suelen asignar una nueva dirección IP local después de un reinicio. Confirma la dirección actual de la máquina que ejecuta Moonraker y actualízala en Printer Tools si ha cambiado. Reservar una dirección estática para ese dispositivo en tu router evita que esto vuelva a pasar.
- 3
Introduce la dirección completa en configuraciones personalizadas
Si Moonraker está detrás de HTTPS, un puerto no estándar o un proxy inverso, introduce la dirección completa exactamente como la escribirías en un navegador. Printer Tools construye la URL del WebSocket a partir de lo que proporcionas, así que una dirección parcial o incorrecta falla antes de que Moonraker llegue a alcanzarse.
- 4
Haz coincidir la autenticación que exige tu instalación
Si Moonraker exige una API key, token Bearer o Basic Auth, hay que introducir las mismas credenciales en Printer Tools. Un desajuste cierra el WebSocket inmediatamente después de abrirse, en lugar de bloquear el intento de conexión inicial.
- 5
Fuerza una reconexión limpia
Elimina y vuelve a añadir la impresora, o desactiva y activa la conexión, para reiniciar el socket desde cero en lugar de esperar al reintento automático. Esto también limpia cualquier solicitud pendiente que hubiera quedado del intento de conexión anterior.
- 6
Descarta la ruta de red
El Wi-Fi de invitados, el aislamiento de clientes, las reglas de firewall de VLAN o un perfil de VPN activo pueden impedir que el móvil alcance el host de la impresora aunque ambos dispositivos muestren acceso a internet. Haz la prueba desde el mismo segmento de red antes de asumir que el problema está en el propio Moonraker.
Estado de Moonraker dentro de Printer Tools
El panel de Klipper refleja el estado en vivo del WebSocket y se actualiza automáticamente en cuanto Moonraker vuelve a estar accesible.
Qué habilita la conexión WebSocket
- Estado de impresión en vivo, progreso, temperaturas y objetos estándar de Klipper enviados en tiempo real
- Reconexión automática cada 5 segundos sin necesidad de volver a abrir la app
- Un heartbeat que mantiene la conexión activa durante el uso normal en segundo plano
- Una comprobación del estado de Klippy realizada inmediatamente después de cada conexión exitosa
- Soporte para API key, token Bearer o Basic Auth cuando tu configuración de Moonraker lo requiera
Lo que esto no puede arreglar
- Un error o estado de apagado de Klippy debe resolverse en el propio Klipper, no desde Printer Tools
- Printer Tools no puede alcanzar un host que cambió de dirección sin actualizar la IP guardada de la impresora
- El aislamiento de red entre el móvil y el host de la impresora bloquea el WebSocket independientemente de la configuración de la app
- Una impresión que ya está en marcha sigue en la impresora aunque la app muestre desconectado
Errores frecuentes del WebSocket
Printer Tools se queda conectando indefinidamente
Confirma que la dirección del host es la actual y es accesible, y que el propio Moonraker está en ejecución. Si la misma dirección también falla en un navegador, el problema está en el host de la impresora, no en la app.
La conexión se abre y luego se cae repetidamente
Comprueba si hay una red que desconecta a los clientes inactivos, como algunas funciones de ahorro de energía Wi-Fi de los routers, o un bucle de reinicio de Moonraker causado por un error de configuración. Revisa el log de Moonraker en el host de la impresora en busca de desconexiones repetidas.
Mainsail o Fluidd se conectan pero Printer Tools no
Usa exactamente la misma dirección, incluyendo esquema y puerto, que funciona en el navegador. Un proxy inverso o un certificado HTTPS que el navegador acepta en silencio puede seguir exigiendo que la dirección completa se introduzca manualmente en Printer Tools.
Klippy muestra un error inmediatamente después de conectar
Esto significa que el WebSocket en sí tuvo éxito y el problema está dentro de la propia configuración de Klipper. Corrige el error indicado en printer.cfg y reinicia Klipper desde Moonraker antes de esperar que Printer Tools muestre un panel normal.
La conexión funciona en casa pero falla fuera de la red local
Un WebSocket directo a Moonraker solo funciona en la misma red local. Usa una VPN de vuelta a tu red doméstica o añade la impresora mediante las opciones de acceso remoto OctoEverywhere u Obico en Printer Tools en lugar de exponer Moonraker directamente.
Reconectar desde fuera de tu red
El WebSocket directo solo funciona mientras el móvil y el host de la impresora comparten una red accesible. Para el acceso remoto, usa una VPN de vuelta a esa red o conecta la misma impresora Klipper mediante OctoEverywhere u Obico en Printer Tools. No redirijas el puerto de Moonraker directamente en tu router.
Preguntas frecuentes
¿Printer Tools usa el WebSocket de Moonraker o su API REST?
Printer Tools se conecta mediante la API WebSocket JSON-RPC de Moonraker en /websocket para telemetría y control en vivo, por eso una ruta de red estable hasta ese endpoint importa más que el éxito de cualquier petición REST aislada.
¿Con qué frecuencia reintenta la app una conexión fallida?
Cada 5 segundos, automáticamente, hasta que el WebSocket vuelve a aceptar la conexión. No hay un límite manual de reintentos que alcanzar.
¿Perder la conexión detiene mi impresión?
No. Klipper sigue imprimiendo en la propia impresora. Que Printer Tools pierda su WebSocket solo significa que la app deja de recibir actualizaciones en vivo hasta que se reconecta.
¿Necesito tener Mainsail o Fluidd en ejecución para que esto funcione?
No. Printer Tools habla directamente con Moonraker. Mainsail y Fluidd son útiles para comparar comportamiento al solucionar problemas, pero ninguno de los dos es obligatorio.
¿Por qué la conexión funciona por Wi-Fi pero no a través de mi VPN?
Una VPN que no enruta tráfico hacia el rango de IP local de tu red doméstica no puede alcanzar Moonraker directamente. Usa una VPN configurada para alcanzar esa red, o usa OctoEverywhere u Obico en su lugar.
Guías relacionadas
Consulta la compatibilidad completa con Klipper y Moonraker
Revisa las funciones de Moonraker compatibles, los requisitos opcionales de cámara y Spoolman, las opciones de acceso remoto y las limitaciones actuales.
Todas tus impresoras 3D en un solo panel
Monitoriza impresoras Bambu Lab, Klipper, OctoPrint, Creality, Snapmaker, Anycubic, Flashforge, Elegoo y Prusa desde una sola app
Disponible en Android, iPhone, iPad y Mac, con apps complementarias para Apple Watch y Wear OS y acceso remoto opcional mediante VPN, OctoEverywhere u Obico
