# Klipper Troubleshooting Pásate por nuestro [**grupo en español de Telegram sobre Klipper**](https://t.me/Klipper_Firmware_ES) para cualquier duda, y por nuestro [**grupo general 3Dwork**](https://t.me/trastornados) si el problema es más general. Os recordamos que tienes más guías de ayuda en **nuestro bot de Telegram** [**@ThreeDWorkHelpBot**](https://t.me/ThreeDWorkHelpBot) *** ## 🆘 Cómo reportar un problema — léelo antes de preguntar Esta sección existe por una razón muy sencilla: **sin información, no hay solución**. Klipper es un sistema complejo con cientos de variables. Decir "me da error" o "no funciona" es el equivalente a llamar al médico y decir "me duele algo". La persona que quiere ayudarte necesita datos reales para poder hacerlo. {% hint style="danger" %} **Las preguntas sin información no se pueden responder.** Antes de publicar en cualquier grupo de soporte asegúrate de haber incluido **como mínimo** el log de Klipper. Sin él, cualquier diagnóstico es pura especulación y pierde el tiempo de todos. {% endhint %} ### Checklist antes de preguntar Marca estos puntos **antes** de publicar en el grupo: * [ ] He leído el mensaje de error **completo** — no solo la primera línea * [ ] He buscado el error en esta guía y en la [documentación oficial de Klipper](https://www.klipper3d.org/) * [ ] He buscado si alguien tuvo el mismo problema en nuestros grupos: [**Klipper ES en Telegram**](https://t.me/Klipper_Firmware_ES) y [**3DWork**](https://t.me/trastornados) * [ ] He revisado el log de Klipper (`klippy.log`) y buscado `!!` para encontrar los errores * [ ] Si el error apareció tras una actualización, he revisado los [cambios de configuración de Klipper](https://github.com/Klipper3d/klipper/blob/master/docs/Config_Changes.md) * [ ] **He ejecutado el script `klipper_logs` por SSH y tengo el enlace listo** (ver sección siguiente — es obligatorio) ### Qué información incluir en tu reporte Usa este template cuando pidas ayuda: ``` 🖨️ MODELO DE IMPRESORA: [ej. Voron 2.4, Ender 3 Pro, etc.] ⚡ ELECTRÓNICA / MCU: [ej. BTT Octopus, SKR Mini E3 v3] 🖥️ HOST: [ej. Raspberry Pi 4, BTT Pi v1.2, Orange Pi Zero 2W] 📦 VERSIÓN KLIPPER: [ver en Mainsail: Settings → About, o en klippy.log] 📦 VERSIÓN MAINSAIL/FLUIDD: [ver en la UI] ❌ DESCRIPCIÓN DEL PROBLEMA: [Describe qué pasa exactamente, cuándo ocurre, si apareció tras algún cambio] 📋 MENSAJE DE ERROR EXACTO: [Copia y pega el mensaje de error completo, no hagas foto de la pantalla] 🔗 LOGS: [link del script klipper_logs o adjunta el klippy.log] ``` {% hint style="warning" %} **Fotos de la pantalla del móvil**: no las mandes. Los logs son texto — cópialos como texto o usa el script de abajo. Una foto de la pantalla hace imposible buscar el error y copiar comandos. {% endhint %} ### 🔗 Compartir los logs en un enlace — el paso más importante {% hint style="success" %} **Esto es lo primero que debes hacer** antes de escribir en cualquier grupo de soporte. Un enlace de logs vale más que mil palabras. Sin logs, cualquier diagnóstico es especulación. {% endhint %} Existe un script SSH desarrollado por [**Andrey Kozhevnikov**](https://coderus.openrepos.net/klipper_logs/) que hace todo el trabajo por ti: se conecta a tu Raspberry Pi / host, recoge automáticamente los logs de Klipper, Moonraker, dmesg y los archivos de configuración, los sube a un servidor web y te devuelve **un enlace listo para pegar en el grupo**. **¿Qué recopila el script?** * `klippy.log` completo (el log principal de Klipper) * `moonraker.log` * Salida de `dmesg` (arranque del sistema y USB) * Archivos de configuración (`printer.cfg` y todos los includes) **Ejecución por SSH** — una sola línea en el terminal: ```bash curl -L https://coderus.openrepos.net/klipper_logs/getlogs | bash -s ``` Si tienes una instalación no estándar o multi-instancia (cambia `printer_2_data` por tu directorio): ```bash curl -L https://coderus.openrepos.net/klipper_logs/getlogs | bash -s -- printer_2_data ``` El script pedirá tu contraseña de usuario (la del host, no la de Klipper), recogerá todos los datos y al finalizar te mostrará algo así: ``` ✅ Logs uploaded. Share this link: https://logs.coderus.openrepos.net/logs/abc123xyz ``` Pega ese enlace en el grupo junto al template de reporte. Es todo lo que necesitan para diagnosticar tu problema. ![](/files/X2HVNUxaRWJNMkJxkW6f) {% hint style="info" %} **Antes de ejecutar el script**, limpia los logs para que solo contengan información del problema actual. Instrucciones en [Log de Klipper](#acceder-al-log-de-klipper) y [Log de Moonraker](#acceder-al-log-de-moonraker). {% endhint %} {% hint style="info" %} **Analizador de logs 3Dwork** — si quieres una primera pista antes de preguntar, pega tu log aquí: {% endhint %} {% hint style="warning" %} Aunque los logs no suelen contener información crítica, compártelos de forma privada con quien te esté ayudando cuando sea posible. Es tu responsabilidad el uso que se haga de esa información. {% endhint %} *** ## 🔍 Diagnóstico inicial — por aquí siempre Antes de ir a secciones específicas, sigue estos pasos en orden. Resuelven el **70% de los casos**: {% stepper %} {% step %} #### 1. Lee el error completo El error de Klipper siempre aparece en la UI (Mainsail/Fluidd) en el banner rojo. Haz clic en él para ver el texto completo. Busca las líneas que empiezan por `!!` en el log — ahí está la causa raíz. {% endstep %} {% step %} #### 2. Comprueba el estado de los servicios ```bash systemctl status klipper systemctl status moonraker ``` Si alguno está en `failed` o `inactive`, ahí está el primer problema. Ve a la sección correspondiente. {% endstep %} {% step %} #### 3. Revisa si el error apareció tras una actualización Si actualizaste Klipper y algo dejó de funcionar, revisa primero: * [Config\_Changes.md](https://github.com/Klipper3d/klipper/blob/master/docs/Config_Changes.md) — cambios que requieren adaptar la configuración * Los errores `option XXX is not valid in section XXX` siempre son de configuración, no de hardware {% endstep %} {% step %} #### 4. Reinicia en el orden correcto Muchos errores transitorios se resuelven con un reinicio ordenado: ```bash sudo systemctl restart klipper sudo systemctl restart moonraker ``` O desde Mainsail: **Power** → reiniciar host si el problema persiste. {% endstep %} {% step %} #### 5. Si nada funciona: reinstala el firmware de la electrónica Los errores de conexión MCU persistentes tras comprobar cableado y configuración casi siempre se resuelven recompilando y reflasheando el firmware Klipper en la electrónica. {% endstep %} {% endstepper %} *** ## Revisión de errores de servicios Cuando un servicio no arranca, estos comandos dan la información detallada: ```bash # Estado resumido del servicio systemctl status klipper # Log completo del servicio (útil para errores de arranque) journalctl -u klipper -n 50 --no-pager # Guardar en fichero para compartir systemctl status klipper > ~/printer_data/logs/klipper_status.txt journalctl -u klipper > ~/printer_data/logs/klipper_journal.txt ``` Aplica lo mismo para `moonraker`, `klipperscreen`, `crowsnest`, etc.
*** ## Klipper El **60% de los problemas** se resuelven con los puntos siguientes. El **39% restante** son problemas de configuración. El **1% final** son bugs reales de Klipper. ### Errores MCU: Serial connection closed / Timeout on connect / Wait for identify\_response Estos errores en el log (`klippy.log`) indican que Klipper no puede comunicarse con la electrónica. **Posibles causas:** * Cable USB de mala calidad, demasiado largo o con conectores flojos * Firmware Klipper no flasheado correctamente en la electrónica (o no flasheado) * Parámetros incorrectos en `make menuconfig` al compilar el firmware * Electrónica dañada (parcialmente o en su comunicación serial) * Versión de firmware en la electrónica desincronizada con la versión del host (ver más abajo) **Diagnóstico:** Desconecta y reconecta la electrónica por USB y ejecuta `sudo dmesg -e`. Una electrónica correctamente conectada debe mostrar algo como: ``` [xxx] usb X-X: New USB device found, idVendor=1d50, idProduct=614e [xxx] usb X-X: Product: lpc1769 [xxx] usb X-X: Manufacturer: Klipper [xxx] cdc_acm X-X:1.0: ttyACMX: USB ACM device ``` Si en `Manufacturer` no pone `Klipper` sino algo como `STMicroelectronics`, el firmware no se flasheó correctamente o la electrónica está en modo DFU. **Soluciones:** 1. Verifica que `ls /dev/serial/by-id/*` muestra tu electrónica y que la ruta coincide exactamente con la que tienes en `[mcu]` de tu `printer.cfg` 2. Recompila y reflashea el firmware con `make menuconfig` verificando procesador, comunicación y bootloader 3. Prueba con otro cable USB (preferiblemente corto y de calidad, con datos — no solo carga) ### Pérdidas de comunicación / Reinicios MCU-Host Causas habituales: * **Alimentación insuficiente en el SBC** — el temido `undervoltage` en Raspberry Pi y similares. Usa fuente oficial o equivalente (5.1V, 3A mínimo), cable USB-C de calidad. Verifica con `vcgencmd get_throttled` — debe devolver `0x0`. * **Temperatura del SBC** — throttling térmico provoca inestabilidad. Añade disipadores o ventilación activa. * **Cable USB largo o de baja calidad** entre host y MCU. * **Retroalimentación USB** — si tu electrónica no tiene jumper de aislamiento entre la alimentación USB y la de la impresora, tapa el pin VBUS del conector USB con cinta.
{% hint style="warning" %} **SBC undervoltage** es la causa número 1 de desconexiones aleatorias en Klipper con Raspberry Pi. Un cable USB de carga barato puede tener suficiente caída de tensión para provocar esto incluso con una buena fuente. {% endhint %} ### Versión de firmware desincronizada Si actualizas Klipper en el host pero no reflasheas el firmware en la electrónica (o viceversa), obtendrás errores de conexión o comportamientos inesperados. **Cómo comprobarlo:** en Mainsail, la sección **System** muestra la versión de Klipper del host y la versión del firmware en cada MCU. Deben coincidir.
**Solución:** recompila y reflashea el firmware en la electrónica cada vez que actualices Klipper en el host. ### Error ADC — fallo en lectura de termistores Klipper se para por seguridad cuando no puede leer correctamente la temperatura de un termistor. **Causas:** * Pin incorrecto en la configuración * Termistor desconectado, dañado o con mala conexión * Tipo de termistor incorrecto en `sensor_type` **Diagnóstico:** ```ini # Verifica en printer.cfg que el sensor_type coincide con el termistor físico # Ejemplo para NTC 100k estándar: [extruder] sensor_type: ATC Semitec 104GT-2 sensor_pin: PA0 ``` Si el pin es correcto, mide la resistencia del termistor con un multímetro (a temperatura ambiente debe ser \~100kΩ para un NTC 100k). Un valor muy diferente indica termistor defectuoso. ### Errores TMC Los drivers TMC pueden reportar errores por varias razones: * **Driver sin alimentación**: los TMC2208/2209/2130/2160 no se inicializan si la electrónica no está alimentada por la fuente de la impresora (solo por USB no es suficiente) * **Driver mal insertado**: verifica que el driver está correctamente colocado en su zócalo y los jumpers de microstepping/UART/SPI están correctos * **Temperatura excesiva del driver**: sin refrigeración adecuada los TMC entran en protección térmica * **Corriente demasiado alta**: baja el `run_current` en la configuración del driver Para errores específicos consulta la [guía oficial de Klipper sobre drivers TMC](https://www.klipper3d.org/TMC_Drivers.html). ### Problemas con CAN bus El CAN bus es cada vez más común (BTT EBB, Mellow FLY-UTOC, etc.) y tiene su propio proceso de diagnóstico. **Verificar que el interface CAN está activo:** ```bash ip link show can0 ``` Si no aparece `can0`, el interface no está configurado. Debe aparecer como `UP` con la bitrate correcta (normalmente 1000000). **Detectar dispositivos CAN:** ```bash ~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0 ``` Esto lista los UUIDs de todos los dispositivos en el bus. Si no aparece tu electrónica: * Verifica el cableado: CANH y CANL deben ir trenzados entre sí (mínimo una vuelta cada 5 cm) * Verifica que hay exactamente **dos resistencias de terminación de 120 Ω** en el bus — una en cada extremo * Comprueba que el conector de alimentación del módulo CAN (U2C, UTOC, etc.) está bien conectado {% hint style="info" %} **120 Ω en ambos extremos es obligatorio.** Un bus CAN sin las resistencias de terminación correctas tendrá comunicación esporádica o nula. Mide con multímetro entre CANH y CANL: debe leer \~60 Ω (las dos resistencias en paralelo). {% endhint %} **Errores `bytes_invalid` incrementando:** ```bash cat /proc/net/can/stats ``` Si el contador `bytes_invalid` no para de crecer, indica errores en el bus. Causas: velocidad de bitrate incorrecta, cableado defectuoso, interferencias. **Tras una actualización de Klipper:** Después de actualizar Klipper en el host, el firmware CAN en las placas cabezal (EBB, etc.) puede quedar desincronizado. Hay que reflashear también esas placas usando Katapult: ```bash python3 ~/katapult/scripts/flashtool.py -i can0 -u -f ~/klipper/out/klipper.bin ``` ### Acelerómetros ADXL345 / MPU-6050 / LIS2DW **Error: `Invalid adxl345 id (got XX vs e5)`:** Problema de inicialización SPI. Intenta de nuevo — si persiste, revisa el cableado (MOSI, MISO, SCK, CS) y la calidad de las soldaduras. Un ID `xx` diferente de `e5` puede indicar sensor defectuoso o falsificado. **Error: `Lost communication with MCU` al ejecutar `ACCELEROMETER_QUERY`:** * Verifica que los pines SPI/I2C en `printer.cfg` son correctos para tu conexión * Si usas SPI por software (`spi_software_*`), prueba reducir la velocidad: `spi_speed: 1000000` * En Orange Pi y algunos SBC el SPI hardware puede ser inestable — prueba con SPI por software **El test de resonancias genera gráficos extraños:** * Asegúrate de que el acelerómetro está bien fijado mecánicamente — cualquier holgura contamina los datos * Ejecuta primero `ACCELEROMETER_QUERY` para verificar que responde antes de lanzar `TEST_RESONANCES` * Los picos múltiples o ruido de fondo alto suelen indicar tornillos del acelerómetro flojos ### Actualizar Klipper, Moonraker y frontends La forma recomendada de actualizar es desde la propia UI de Mainsail/Fluidd (sección **Update Manager**), que actualiza todos los componentes de forma coordinada. Si prefieres hacerlo por SSH: ```bash # Actualizar Klipper cd ~/klipper git pull sudo systemctl restart klipper # Actualizar Moonraker cd ~/moonraker git pull sudo systemctl restart moonraker ``` {% hint style="warning" %} **Después de actualizar Klipper siempre:** 1. Revisa [Config\_Changes.md](https://github.com/Klipper3d/klipper/blob/master/docs/Config_Changes.md) por si hay cambios que afectan a tu configuración 2. Recompila y reflashea el firmware en **todas** tus MCUs (placa principal + cabezales CAN si los tienes) {% endhint %} **Volver a una versión anterior de Klipper:** ```bash cd ~/klipper git log --oneline -10 # ver commits recientes git checkout # volver a un commit específico sudo systemctl restart klipper ``` ### Error: `Heater not heating at expected rate` / `Heating timeout` {% hint style="danger" %} **Errores típicos:** ``` Heater extruder not heating at expected rate Heating timeout: Extruder did not reach target temperature Heater bed not heating at expected rate ``` Klipper monitoriza que el calentador sube de temperatura a un ritmo razonable. Si en 20 segundos no sube al menos 2 °C, cancela por seguridad. {% endhint %} **Causas y soluciones:** | Causa | Diagnóstico | Solución | | ------------------------------------- | ----------------------------------------------- | -------------------------------------------------- | | PID no calibrado (oscilaciones) | Temperatura sube y baja sin estabilizarse | Ejecuta `PID_CALIBRATE HEATER=extruder TARGET=200` | | Tipo de termistor incorrecto | Temperatura en pantalla muy diferente a la real | Verifica `sensor_type` en `printer.cfg` | | Cartucho calentador defectuoso | No sube temperatura o sube muy lento | Mide resistencia del cartucho (\~15-25 Ω a 24V) | | Entorno muy frío / corrientes de aire | Funciona en verano, falla en invierno | Encierra la impresora o aumenta `heating_gain` | | Tensión de alimentación baja | LED del hotend tenue | Mide voltaje en fuente: debe ser 24V ±0,5V | | Pin del calentador incorrecto | Nunca calienta | Verifica `heater_pin` en la configuración | **Cómo recalibrar el PID:** ```bash # Para el hotend (reemplaza el target por tu temperatura habitual de impresión) PID_CALIBRATE HEATER=extruder TARGET=200 # Para la cama PID_CALIBRATE HEATER=heater_bed TARGET=60 # Al terminar, guarda los nuevos valores SAVE_CONFIG ``` {% hint style="info" %} Si el error ocurre solo con cama de gran formato (300×300 mm o más), es normal que tarde más en calentar. Puedes ajustar en `printer.cfg`: ```ini [heater_bed] heating_gain: 2 # tiempo mínimo de calentamiento (segundos por grado) ``` {% endhint %} ### Errores de homing / Endstop **Error: `Endstop 'x' still triggered after retract`** El endstop sigue reportando activado incluso después de que el cabezal retrocedió. Causas: * **Polaridad invertida**: prueba añadir o quitar el `!` en el pin (`endstop_pin: !PG6` ↔ `endstop_pin: PG6`) * **Endstop mecánico dañado**: con un multímetro en modo continuidad, verifica que el switch se abre y cierra correctamente al pulsarlo * **Cableado**: cable cortocircuitado o con mala conexión **Error: `Endstop 'x' not triggered` / `Homing failed: Timeout`** El eje llega al límite de movimiento sin que el endstop lo detecte. Causas: * **Posición del endstop**: el cabezal no alcanza el sensor antes de llegar al límite de recorrido del eje * **Pin incorrecto**: verifica que `endstop_pin` apunta al pin físico correcto según el pinout de tu electrónica * **Conector suelto**: revisa el conector del endstop en la placa **Diagnóstico rápido desde la consola:** ```bash # Comprueba el estado actual de todos los endstops QUERY_ENDSTOPS ``` Con el endstop en reposo debe mostrar `open`. Al pulsarlo manualmente debe cambiar a `TRIGGERED`. Si siempre muestra `TRIGGERED` o nunca cambia, el problema es físico o de polaridad. {% hint style="warning" %} Con **sensores virtuales** (sensorless homing con TMC) los errores de homing son más difíciles de diagnosticar. El parámetro `driver_SGTHRS` (sensibilidad de stall) debe ajustarse para cada máquina. Consulta la [guía de sensorless homing](https://www.klipper3d.org/TMC_Drivers.html#sensorless-homing). {% endhint %} ### Errores de probe (BLTouch / CR Touch / Klicky / Beacon) **BLTouch / CR Touch — `BLTouch failed to deploy` o no retrae la aguja** ``` BLTouch failed to deploy BLTouch failed to verify sensor state ``` | Síntoma | Causa probable | Solución | | -------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- | | Aguja no baja al enviar `BLTOUCH_DEBUG COMMAND=pin_down` | Fallo eléctrico o de señal | Verifica los 5 cables: GND, 5V, GND señal, IN, OUT | | Aguja baja pero no sube | Mecanismo interno atascado | Limpia el interior con aire comprimido; puede necesitar reemplazo | | Probe triggered antes de tocar | Interferencias eléctricas | Añade condensador 100nF entre GND y la señal del probe | | Error intermitente | `probe_count` muy alto o velocidad excesiva | Reduce velocidad: `speed: 2` en `[probe]` | **Probe triggered prior to movement / probe already triggered:** Klipper detecta el probe activo antes de intentar la medición. Causas: * Aguja BLTouch bajada por un reset previo — envía `BLTOUCH_DEBUG COMMAND=reset` * Polaridad incorrecta en `pin_up_reports_not_triggered` o `pin_up_touch_mode_reports_triggered` **Calibración del offset Z del probe:** Recuerda que el `z_offset` debe medirse con `PROBE_CALIBRATE` y guardarse con `SAVE_CONFIG`. Un offset incorrecto provoca que la primera capa sea demasiado alta o que el nozzle choque contra la cama. ```bash # Lanza el asistente de calibración del probe PROBE_CALIBRATE # Al terminar, mueve Z manualmente hasta que una hoja de papel deslice con ligera resistencia # Acepta con: ACCEPT SAVE_CONFIG ``` {% hint style="info" %} Para una guía completa sobre todos los sensores de nivelación compatibles con Klipper (BLTouch, CR Touch, Klicky, Beacon, Eddy, inductivos...) consulta: [Sensor de nivelación — guía completa](https://klipper.3dwork.io/klipper/empezamos/sensor-nivelacion) {% endhint %} {% hint style="info" %} **Sensores de inducción** (como el PL-08N): verifica que el voltaje de salida (NPN vs PNP) es compatible con tu electrónica. Un sensor PNP con una entrada NPN puede quemar el pin de la placa. {% endhint %} ### Errores de configuración: `option XXX is not valid in section XXX` Estos errores indican un problema en el parser del fichero de configuración. El log siempre indica el fichero y la línea exacta. **Causas habituales:** * Opción con nombre incorrecto o desactualizado * Valor fuera del rango permitido * Sección duplicada (Klipper carga los includes de forma secuencial; la última definición prevalece) **Cambios de configuración frecuentes tras actualizar:** {% tabs %} {% tab title="minimum\_cruise\_ratio" %} Desde el 13/03/2024, `max_accel_to_decel` fue reemplazado por `minimum_cruise_ratio`. {% code title="Antes" %} ```ini [printer] max_accel: 1500 max_accel_to_decel: 750 ``` {% endcode %} {% code title="Ahora" %} ```ini [printer] max_accel: 1500 minimum_cruise_ratio: 0.5 ``` {% endcode %} `minimum_cruise_ratio: 0.5` es equivalente a `max_accel_to_decel` = 50% de `max_accel`. Si no defines este parámetro, Klipper usará 0.5 por defecto. {% endtab %} {% tab title="homing\_retract\_dist con scanners" %} Con sensores tipo Beacon, Cartographer o Voron TAP, hay que añadir en `[stepper_z]`: ```ini [stepper_z] homing_retract_dist: 0 ``` Sin esta línea Klipper intentará hacer una segunda pasada de homing que chocará con la cama. {% endtab %} {% endtabs %} Consulta el historial completo de cambios en: ### Error: `Move exceeds maximum extrusion` {% hint style="danger" %} **Error típico:** ``` ! Move exceeds maximum extrusion (X.XXXmm^2 vs 0.640mm^2) ``` Este error aparece cuando Klipper detecta que la cantidad de filamento a extruir en un movimiento es desproporcionada respecto a la distancia recorrida. El valor `0.640mm^2` es el límite por defecto para una boquilla de 0,4 mm. {% endhint %} #### ¿Por qué ocurre? Klipper calcula la sección transversal de la extrusión en cada movimiento: `mm_de_filamento / mm_de_desplazamiento`. Si ese cociente supera el parámetro `max_extrude_cross_section` del bloque `[extruder]`, detiene la impresión. | Causa habitual | Por qué lo provoca | | ----------------------------------------------- | ---------------------------------------------------------- | | Línea de purga sin desplazamiento (o muy corto) | Extruye mucho filamento con muy poco movimiento | | Macro `START_PRINT` con purgado estático | Igual que arriba: purga concentrada en un punto | | Torre de purga (AMS / MMU / ERCF) | El cambio de color extruye en un área pequeña | | Mismatch `M82` / `M83` (absoluto vs relativo) | Klipper interpreta la posición E como longitud enorme | | Boquilla grande (0,6 mm o más) | La sección transversal natural es mayor y supera el límite | #### Solución 1 — Ajustar `max_extrude_cross_section` En `printer.cfg`, dentro del bloque `[extruder]`: ```ini [extruder] max_extrude_cross_section: 5 # boquilla 0,4 mm # max_extrude_cross_section: 10 # boquilla 0,6 mm # max_extrude_cross_section: 15 # boquilla 0,8 mm o multicolor ``` {% hint style="warning" %} No pongas valores de millones (ej. `99999999`). Eso desactiva la protección por completo y puede provocar atascos o daños al hotend. Un valor de **5–20** es suficiente para todos los casos normales. {% endhint %} #### Solución 2 — Corregir la línea de purga en el laminador La purga debe **mover el cabezal mientras extruye**. Ejemplo correcto en el G-code de inicio: ```gcode ; Mover al punto de inicio de purga G1 X5 Y5 Z0.3 F3000 ; Purgar extrudiendo A LA VEZ que se mueve G1 X120 E15 F1500 ; Retraer y resetear la posición E G92 E0 ``` Si usas la macro `START_PRINT`, asegúrate de que la purga incluye `G92 E0` al final y que el cabezal se desplaza durante la extrusión. Consulta la guía de [configuración Klipper en laminadores](https://github.com/alienboyxp/gitbook_es_klipper_3dwork_io/blob/main/empezamos/configuracion-klipper-en-laminadores.md) para la estructura completa de la macro. #### Solución 3 — Revisar el modo de extrusión (`M82` / `M83`) Si el error muestra un valor de extrusión enorme (cientos o millones de mm²), el problema es casi seguro un mismatch de modo absoluto/relativo: * `M82` → extrusión **absoluta** (el valor E es posición acumulada) * `M83` → extrusión **relativa** (el valor E es incremento por movimiento) Verifica que tu laminador y tu macro `START_PRINT` usan el mismo modo. Lo más seguro es añadir `M83` explícito al inicio de la macro y `G92 E0` tras cualquier purga. #### Solución 4 — Impresión multicolor (AMS / MMU / ERCF) Las torres de purga y los purge buckets generan extrusiones de alta densidad. Aumenta el límite: ```ini [extruder] max_extrude_cross_section: 15 # o 20 para torres grandes ``` Y asegúrate de que los scripts de cambio de filamento incluyen `G92 E0` antes de reanudar la impresión. ### Acceder al log de Klipper {% tabs %} {% tab title="UI (Mainsail/Fluidd)" %} En Mainsail: **MACHINE → Log Files → klippy.log**
{% hint style="info" %} Para limpiar el log antes de reproducir el error (muy recomendable para el diagnóstico): haz clic en el icono de papelera junto a `klippy.log`. {% endhint %} {% endtab %} {% tab title="SSH" %} ```bash # Localización del log $HOME/printer_data/logs/klippy.log # Limpiar el log (para reproducir el error en limpio) : > ~/printer_data/logs/klippy.log sudo systemctl restart klipper # Ver las últimas líneas en tiempo real tail -f ~/printer_data/logs/klippy.log # Extraer información de un fallo de apagado mkdir ~/work_dir && cd ~/work_dir cp ~/printer_data/logs/klippy.log . ~/klipper/scripts/logextract.py ./klippy.log ``` {% endtab %} {% endtabs %} ### Reiniciar el servicio Klipper {% tabs %} {% tab title="UI (Mainsail)" %}
{% endtab %} {% tab title="SSH" %} ```bash sudo systemctl stop klipper # parar sudo systemctl start klipper # iniciar sudo systemctl restart klipper # reiniciar ``` {% endtab %} {% endtabs %} *** ## Mainsail / Fluidd ### Requerimientos en printer.cfg Mainsail y Fluidd necesitan ciertas secciones en `printer.cfg` para funcionar correctamente. Si ves errores de acceso a gcodes o funciones que no aparecen, probablemente falta alguna de estas: {% hint style="success" %} La forma más sencilla es añadir el include correspondiente a tu `printer.cfg`: ```ini [include mainsail.cfg] # para Mainsail # o [include fluidd.cfg] # para Fluidd ``` Si no tienes ese fichero, créalo a partir de: * Mainsail: * Fluidd: {% endhint %} Si necesitas añadirlas manualmente: ```ini [pause_resume] [display_status] [virtual_sdcard] path: ~/printer_data/gcodes on_error_gcode: CANCEL_PRINT ``` ### Errores de acceso a gcodes — "Unable to open file"
**Causas:** 1. El path de `[virtual_sdcard]` no existe o es incorrecto 2. El usuario de Klipper no tiene permisos sobre ese directorio **Solución:** ```bash # Verificar que el directorio existe ls ~/printer_data/gcodes # Si no existe, crearlo mkdir -p ~/printer_data/gcodes # Corregir permisos (sustituye 'pi' por tu usuario si es diferente) chown pi ~/printer_data/gcodes chmod 755 ~/printer_data/gcodes ``` *** ## Crowsnest ### Upgrade v3 a v4 Si tu webcam dejó de funcionar después de una actualización de Crowsnest, probablemente sea el cambio v3→v4 que modificó completamente la arquitectura del componente. {% embed url="" %} ### Webcam no aparece en la UI ```bash # Listar dispositivos de vídeo detectados ls /dev/video* # Ver log de Crowsnest journalctl -u crowsnest -n 50 --no-pager ``` Si no hay ningún `/dev/video*`, el problema es de reconocimiento del dispositivo (driver), no de Crowsnest. *** ## Moonraker ### Incidentes históricos
Octubre 2022 — Cambio de estructura de directorios Moonraker cambió la estructura de carpetas esperada. Síntoma: después de actualizar, Moonraker no se comunica con Klipper o no hay acceso a ficheros de configuración desde la UI. ![](/files/YgTSAfR9Bn31dss4MShz) La estructura correcta es: ``` ~/printer_data/ ├── config/ → printer.cfg, moonraker.conf, etc. ├── database/ → base de datos Moonraker ├── gcodes/ → ficheros gcode ├── logs/ → klippy.log, moonraker.log └── systemd/ → moonraker.env ``` Para adaptar una instalación antigua, ejecuta el script incluido en Moonraker: ```bash cd ~/moonraker git pull ./scripts/data-path-fix.sh ```
Enero 2022 — Problema de permisos PolicyKit Moonraker cambió de `sudo` a D-Bus para comunicarse con el sistema. Síntoma: aviso de PolicyKit en la UI. ![](/files/R3v4UfIo6rCRhAvmGri0) ```bash cd ~/moonraker/scripts ./set-policykit-rules.sh sudo systemctl restart moonraker ``` Si el script da errores: ```bash sudo apt update && sudo apt install packagekit ```
### Acceder al log de Moonraker {% tabs %} {% tab title="UI (Mainsail)" %} **MACHINE → Log Files → moonraker.log**
{% endtab %} {% tab title="SSH" %} ```bash # Localización $HOME/printer_data/logs/moonraker.log # Limpiar : > ~/printer_data/logs/moonraker.log sudo systemctl restart moonraker # Ver en tiempo real tail -f ~/printer_data/logs/moonraker.log ``` {% endtab %} {% endtabs %} ### Reiniciar Moonraker {% tabs %} {% tab title="UI (Mainsail)" %}
{% endtab %} {% tab title="SSH" %} ```bash sudo systemctl restart moonraker ``` {% endtab %} {% endtabs %} *** ## KlipperScreen KlipperScreen tiene su propia documentación de troubleshooting muy completa que cubre la mayoría de problemas: {% embed url="" %} Los problemas más frecuentes son: * **Pantalla en negro tras arrancar**: verifica la configuración del display en `/boot/config.txt` (para Raspberry Pi) o el overlay correspondiente para tu SBC * **Touch no responde**: verifica la calibración táctil y los parámetros del overlay * **KlipperScreen no conecta con Klipper**: revisa que Moonraker está funcionando y que la IP/socket en la configuración de KlipperScreen es correcta ```bash # Log de KlipperScreen journalctl -u KlipperScreen -n 50 --no-pager ``` *** ## Creality Sonic Pad {% hint style="warning" %} **El Creality Sonic Pad fue descontinuado por Creality en 2024.** Si buscas una solución similar (Klipper en hardware dedicado), considera las alternativas: **BTT Pad 7** o cualquier SBC genérico con MainsailOS/FluiddOS. {% endhint %} La Sonic Pad usa una MCU Creality T800 sobre una distribución Linux especial (Tina, fork de OpenWRT para Allwinner). Los componentes Klipper que incluye son versiones muy antiguas y no actualizables directamente por el usuario. **Por qué el grupo no da soporte habitual a la Sonic Pad:** * Hardware propietario con poca documentación pública * Klipper, Moonraker y Mainsail muy desactualizados (no se pueden actualizar sin intervención de Creality) * Sin acceso a muchas funciones modernas de Klipper (macros, electrónicas nuevas, etc.) * La comunidad no puede reproducir los problemas sin tener el hardware específico **Si tienes una Sonic Pad y quieres Klipper oficial sin estas limitaciones**, existe un firmware alternativo no oficial: {% content-ref url="/pages/YueUijEFKUo1HCuzEMwS" %} [Creality Sonic Pad - Klipper Oficial, custom firmware](/klipper/instalacion/guias-instalacion-especificas-impresora-electronica/creality-klipper/creality-sonic-pad-klipper-oficial-custom-firmware.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://klipper.3dwork.io/klipper/troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.