Ctrlk
KLIPPERMARLINLABSTelegramColabora3DWORK AI Agent
instagramyoutubetiktok
For the complete documentation index, see llms.txt. This page is also available as Markdown.

‼️Klipper Troubleshooting

Guía completa de resolución de problemas en Klipper: diagnóstico, errores MCU, TMC, CAN bus, ADXL, configuración y cómo reportar correctamente en los grupos de soporte.

Pásate por nuestro grupo en español de Telegram sobre Klipper para cualquier duda, y por nuestro grupo general 3Dwork si el problema es más general.

Os recordamos que tienes más guías de ayuda en nuestro bot de Telegram @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.

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.

Checklist antes de preguntar

Marca estos puntos antes de publicar en el grupo:

Qué información incluir en tu reporte

Usa este template cuando pidas ayuda:

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.

🔗 Compartir los logs en un enlace — el paso más importante

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.

Existe un script SSH desarrollado por Andrey Kozhevnikov 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:

Si tienes una instalación no estándar o multi-instancia (cambia printer_2_data por tu directorio):

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í:

Pega ese enlace en el grupo junto al template de reporte. Es todo lo que necesitan para diagnosticar tu problema.

Antes de ejecutar el script, limpia los logs para que solo contengan información del problema actual. Instrucciones en Log de Klipper y Log de Moonraker.

Analizador de logs 3Dwork — si quieres una primera pista antes de preguntar, pega tu log aquí:

https://3dwork.io/tools/index.html#loganalyzer

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.

🔍 Diagnóstico inicial — por aquí siempre

Antes de ir a secciones específicas, sigue estos pasos en orden. Resuelven el 70% de los casos:

1

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.

2

2. Comprueba el estado de los servicios

Si alguno está en failed o inactive, ahí está el primer problema. Ve a la sección correspondiente.

3

3. Revisa si el error apareció tras una actualización

Si actualizaste Klipper y algo dejó de funcionar, revisa primero:

  • 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

4

4. Reinicia en el orden correcto

Muchos errores transitorios se resuelven con un reinicio ordenado:

O desde Mainsail: Power → reiniciar host si el problema persiste.

5

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.

Revisión de errores de servicios

Cuando un servicio no arranca, estos comandos dan la información detallada:

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:

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.

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.

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:

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.

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:

Si no aparece can0, el interface no está configurado. Debe aparecer como UP con la bitrate correcta (normalmente 1000000).

Detectar dispositivos CAN:

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

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

Errores bytes_invalid incrementando:

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:

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:

Después de actualizar Klipper siempre:

  1. Revisa 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)

Volver a una versión anterior de Klipper:

Error: Heater not heating at expected rate / Heating timeout

Errores típicos:

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.

Primero: ¿hardware o configuración?

Antes de tocar el PID, descarta un problema de hardware. Si la temperatura no sube nada (o sube muy lento) el PID no es el culpable: un PID desajustado provoca oscilaciones, no que el calentador no caliente.

Síntoma
Causa probable
Tipo

No sube nada de temperatura

heater_pin incorrecto, cartucho/resistencia rota, cable suelto, MOSFET/salida dañada

Hardware / cableado

Sube muy lento o se queda a medio camino

Tensión baja (debe ser 24 V ±0,5 V), cartucho defectuoso (~15-25 Ω a 24 V), aislamiento del hotend/cama deficiente

Hardware

Temperatura en pantalla muy distinta a la real, o lecturas erráticas

sensor_type incorrecto, termistor o conector defectuoso

Configuración / hardware

Sube, se pasa del objetivo y oscila sin estabilizarse

PID no calibrado o muy desajustado

Configuración (PID)

Falla solo en invierno / con corrientes de aire, o con cama grande (300×300 o más)

Pérdidas térmicas altas: encerrar la impresora o ajustar verify_heater

Entorno / configuración

Diagnóstico rápido:

  1. Con el calentador a temperatura ambiente, pide un objetivo bajo (p. ej. 60 °C) desde la interfaz web y observa la gráfica: si sube de forma continua, el hardware funciona.

  2. Comprueba con un multímetro la resistencia del cartucho y la tensión en la fuente.

  3. Revisa heater_pin, sensor_type y sensor_pin en printer.cfg.

  4. Si el hardware es correcto y la curva oscila, calibra el PID.

Calibrar el PID (procedimiento estándar):

También puedes usar las macros PID_EXTRUDER, PID_BED y PID_ALL del 3Dwork Klipper Bundle.

PID seguro en configuraciones muy desajustadas

Si la configuración está tan desajustada que la propia protección térmica (verify_heater) aborta el PID_CALIBRATE antes de terminar, relaja temporalmente y solo para hacer el PID estos parámetros, y vuelve a los valores por defecto después:

Si las lecturas del termistor son ruidosas, suaviza la medición mientras calibras:

Después: FIRMWARE_RESTART, lanza el PID_CALIBRATE, ejecuta SAVE_CONFIG y revierte los valores relajados. Deja siempre verify_heater activo en funcionamiento normal: es la protección contra fallos del calentador.

📚 Guía de referencia completa (macros, log con WRITE_FILE=1, valores que no se guardan, etc.): Calibración de impresoras 3D → Klipper - PID.

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:

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.

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.

Errores de probe (BLTouch / CR Touch / Klicky / Beacon)

BLTouch / CR Touch — BLTouch failed to deploy o no retrae la aguja

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.

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

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.

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:

Desde el 13/03/2024, max_accel_to_decel fue reemplazado por minimum_cruise_ratio.

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.

Con sensores tipo Beacon, Cartographer o Voron TAP, hay que añadir en [stepper_z]:

Sin esta línea Klipper intentará hacer una segunda pasada de homing que chocará con la cama.

Consulta el historial completo de cambios en: https://github.com/Klipper3d/klipper/blob/master/docs/Config_Changes.md

Error: Move exceeds maximum extrusion

Error típico:

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.

¿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]:

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.

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:

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

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

En Mainsail: MACHINE → Log Files → klippy.log

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.

Reiniciar el servicio Klipper

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:

La forma más sencilla es añadir el include correspondiente a tu printer.cfg:

Si no tienes ese fichero, créalo a partir de:

Si necesitas añadirlas manualmente:

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:

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.

LogoCrowsnest - Webcam Streaming Daemon for 3D printerscrowsnest.mainsail.xyz

Webcam no aparece en la UI

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.

La estructura correcta es:

Para adaptar una instalación antigua, ejecuta el script incluido en Moonraker:

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.

Si el script da errores:

Acceder al log de Moonraker

MACHINE → Log Files → moonraker.log

Reiniciar Moonraker

KlipperScreen

KlipperScreen tiene su propia documentación de troubleshooting muy completa que cubre la mayoría de problemas:

LogoFirst Steps/Log - KlipperScreenklipperscreen.readthedocs.io

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

Creality Sonic Pad

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.

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:

Creality Sonic Pad - Klipper Oficial, custom firmware
AnteriorRecuperar impresión fallida en Klipper
SiguienteCreality

Última actualización