Klipper Log Analysis for Voron — Reading klippy.log and Debugging

Klipper Troubleshooting Guide

When something goes wrong on your Voron, Klipper's logs are the single most valuable diagnostic resource you have. Every MCU command, every sensor reading, every error, and every shutdown event is recorded with millisecond timestamps. Learning to read these logs effectively can turn hours of blind troubleshooting into a targeted, five-minute fix. This guide covers every log file in a standard Klipper installation, how to interpret common error messages, and how to extract the data you need to diagnose almost any problem. Last updated: May 2025.

Log File Locations and Purpose

A typical Voron running Klipper on a Raspberry Pi or similar host generates several log files. Each serves a different purpose:

~/printer_data/logs/klippy.log — The main Klipper log. Contains every command sent to and from the MCU, all sensor readings, stepper positions, and error messages. This is the first file you should check for any print issue.
~/printer_data/logs/moonraker.log — The Moonraker API server log. Tracks HTTP requests, WebSocket connections, file operations, update manager activity, and database operations. Check this if Fluidd or Mainsail won't connect or if updates fail.
~/printer_data/logs/klippy.log.1, klippy.log.2, ... — Rotated log archives. Klipper keeps the last five rotated logs by default. These are useful for comparing behavior before and after a config change or for recovering error history after a restart.
~/printer_data/logs/crowsnest.log — Webcam streaming server log. Check here if your webcam feed isn't working.
dmesg — System-level kernel log (not a Klipper file). Useful for detecting USB disconnects, power issues, or hardware-level failures on the host.

Understanding the Log Format

Every line in klippy.log begins with a millisecond timestamp relative to when Klipper started, followed by a log level indicator:

009.123 [INFO] This is an informational message
012.456 [WARNING] Something might be wrong but the system can continue
015.789 [ERROR] Something went wrong
018.012 [DEBUG] Detailed diagnostic information (requires debug level to be enabled)

The timestamp format is seconds.milliseconds from Klipper startup. Line 000.000 is the moment Klipper began initializing. To correlate log events with real time, look for the initial timestamp near the top where Klipper records the system clock value at startup.

Reading the Startup Section

The first 50-100 lines of klippy.log after a fresh start contain critical diagnostic information. This section tells you:

Which Klipper version is running
Which MCU firmware versions are connected
Whether all configured MCUs were detected
Which config file was loaded (and any include errors)
The pin mappings for every configured component
Initial heater and thermistor readings

Look for these specific patterns in the startup log:

000.000 [INFO] Starting Klipper version v0.12.0-123-gabcdef1
000.023 [INFO] Loaded config file: /home/pi/printer_data/config/printer.cfg
000.456 [INFO] MCU 'mcu' connected: BTT Octopus v1.1 (F407)
000.789 [INFO] MCU 'toolhead' connected: EBB36 v1.2 (USB)
001.234 [INFO] Configured heaters: extruder (PID), heater_bed (PID)
001.567 [INFO] Configured temperature sensors: extruder, heater_bed, chamber

If an MCU fails to connect, you'll see an ERROR line with the connection details and the specific failure reason. Common connection errors include:

"No such device" — The MCU is not physically connected or powered
"Permission denied" — The user doesn't have access to the serial port
"Protocol error" — Firmware version mismatch between Klipper and the MCU
"Can not update config" — The MCU already has firmware but the config is incompatible

Common Error Messages and Their Meanings

Lost Communication with MCU

045.678 [ERROR] MCU 'mcu' shutdown: Lost communication with MCU
045.678 [ERROR] This is frequently caused by power supply issues
045.678 [ERROR] Check that the 24V power supply is connected and stable

This is one of the most common Klipper errors. It means the host (Raspberry Pi) stopped receiving responses from the MCU. The error text is generated by the host, not the MCU, and is often accompanied by timing statistics showing how long the communication was stalled. Common causes include:

USB cable issues — Try a different cable, a different USB port, or add a ferrite bead. USB micro-B connectors on Raspberry Pis are mechanically weak.
Power supply brownout — If the PSU voltage drops below the MCU's minimum operating voltage, the MCU will reset. Measure the 24V rail under load.
Electrical noise from heaters — If the disconnects happen when the bed or hotend heater is switching, you may have inductive kickback interfering with USB or serial communication.
Overloaded USB bus — Too many USB devices on a single Raspberry Pi USB port can cause intermittent disconnects. Use a powered USB hub.

Timer Too Close / Stepper Too Far in Past

123.456 [ERROR] MCU 'mcu' shutdown: Timer too close
123.456 [ERROR] This event has been triggered by a command that requires the
                MCU to process an event in the past. This is generally caused by
                the host computer not being fast enough.

This error means the Raspberry Pi couldn't send stepper commands fast enough to keep up with the requested motion. It's a host performance issue, not an MCU issue. Look for:

CPU overload — Check if something else is consuming CPU on the Pi. OctoPrint plugins, webcam streaming at high resolution, or database backups can steal CPU time from Klipper.
SD card latency — If you're logging at DEBUG level to a slow SD card, the I/O wait can cause timing issues.
Spiral vase mode or very small layer heights — These require frequent small moves that can overwhelm the host. Run STATUS during printing to see if Klipper reports being behind schedule.
Extremely high microstepping — 256 microstepping generates many more steps per mm than 16 microstepping, increasing the host-to-MCU communication load.

Heater Not Heating at Expected Rate

234.567 [ERROR] Heater 'extruder' not heating at expected rate
234.567 [ERROR] See 'verify_heater' section in docs for more info

This safety check fires when the temperature doesn't rise fast enough after being commanded to heat. Possible causes:

Failed heater cartridge — Measure resistance with a multimeter. A 40W heater cartridge should read approximately 14-16 ohms. An open circuit (infinite resistance) means the heater is dead.
MOSFET failure on the mainboard — If the MOSFET is stuck open or closed, the heater may not receive power. Try a different heater output on the board if available.
Thermistor reading incorrectly — If the thermistor reports a temperature much higher than actual, the firmware may think the heater is doing nothing. Check the thermistor resistance at room temperature (100K thermistors should read ~100K ohms at 25°C).
PID parameters are extremely wrong — If you copied PID values from a different printer or hotend, they may be so far off that the heater never reaches the target.

Reading klippy.log for Print Quality Issues

Beyond error messages, klippy.log contains a wealth of diagnostic data about normal operation. You can extract performance metrics and identify subtle issues before they become print failures.

Position Data and Stepper Following Errors

Klipper logs every "position_endstop" event and every "stepper position" change at INFO level. If you suspect layer shifting, search for:

450.123 [INFO] Actual position: X=100.000, Y=100.000, Z=20.000
450.124 [INFO] Stepper 'stepper_x' position: 100.000
450.125 [INFO] Stepper 'stepper_y' position: 100.000

During a shift event, you would see the stepper position jump unexpectedly or fail to track the commanded position. This confirms a physical step loss or mechanical skip, ruling out a firmware issue.

Temperature History

Klipper logs heater temperatures and power levels during printing. This data is invaluable for diagnosing thermal issues:

500.000 [INFO] Read extruder temperature: 245.0 -> 245.3 (pwm=0.312)
500.100 [INFO] Read heater_bed temperature: 110.0 -> 110.1 (pwm=0.450)

A temperature that oscillates more than 2-3°C around the target indicates poor PID tuning. A temperature that gradually drops over time while PWM stays at 100% indicates the heater can't keep up — either the heater is underpowered or there's excessive heat loss (e.g., a draft in an open-frame Voron).

Moonraker Log Analysis

Moonraker.log records API activity, file operations, and update management. It's less frequently needed than klippy.log but is essential for certain issues:

Web UI connectivity issues — Search for "Failed to bind" or "Connection refused" to find port conflicts or firewall issues.
Failed firmware updates — Moonraker's update manager logs detailed information about git pull operations, package installations, and build failures.
Database corruption — "database disk image is malformed" indicates the Moonraker SQLite database is corrupted. Moonraker keeps an aside copy that can be used for recovery.
Authorization failures — "Invalid API key" or "Unauthorized" errors when trying to access the API from external tools.

Enabling Debug Logging

Sometimes the default INFO log level doesn't provide enough detail. You can enable DEBUG-level logging by adding to printer.cfg:

# Enable debug logging for detailed stepper and MCU communication
# Add this section to printer.cfg and restart Klipper
[logging]
level: debug
# WARNING: Debug logging generates a LOT of data
# On a Raspberry Pi, this can fill the SD card within hours
# Enable only for targeted debugging sessions and disable after

With debug logging enabled, you'll see every serial command sent to the MCU, every timer callback, and detailed scheduling information. This is useful for:

Diagnosing "Timer too close" errors with microsecond-level timing data
Verifying that input shaper commands are being processed correctly
Debugging custom macros and the timing of gcode command execution

Important: Debug logging generates approximately 10-50 MB per hour of printing. On a Raspberry Pi with a 32GB SD card, you have about 500-1000 hours before the card fills. Always disable debug logging after you've captured the data you need.

Using grep to Extract Relevant Log Data

For large log files, manually reading through thousands of lines is impractical. Using grep (or the search functionality in Fluidd/Mainsail's log viewer) lets you find relevant sections quickly:

# Get the last 500 lines (most recent activity)
tail -500 ~/printer_data/logs/klippy.log

# Search for all ERROR lines
grep "ERROR" ~/printer_data/logs/klippy.log

# Search for a specific MCU's shutdown events
grep -i "shutdown" ~/printer_data/logs/klippy.log

# Extract temperature readings for plotting
grep "Read extruder temperature" ~/printer_data/logs/klippy.log

# Find the startup section (first 100 lines)
head -100 ~/printer_data/logs/klippy.log

# Correlate with real time by finding the startup timestamp
grep "Configured" ~/printer_data/logs/klippy.log

For more complex analysis, you can pipe log data to separate tools:

# Extract temperature vs time data for graphing
grep "Read extruder temperature" klippy.log   | awk '{print $1, $5}'   | tr -d ','   > temp_data.csv

This generates a CSV file with timestamp and temperature columns that you can import into any spreadsheet application for visualization.

Log Rotation and Management

By default, Klipper rotates logs when they reach 5 MB, keeping 3 backups:

# Check current log rotation config (in printer.cfg)
[logging]
level: info
log_rotation_size: 5242880  # 5 MB
log_rotation_count: 3

# To keep more history, increase these values
# log_rotation_size: 10485760  # 10 MB
# log_rotation_count: 5

If you want to archive logs for historical comparison (e.g., comparing last month's behavior to this month's), copy them to a separate directory or offload them to another machine. Logs are plain text and compress extremely well:

# Compress an old log for archival
gzip -k klippy.log.3
# Size typically reduces by 80-90%

Creating a Log-Based Diagnostic Workflow

When a print fails, follow this log-first diagnostic workflow before touching the printer:

Open the most recent klippy.log (or the one that spans the failed print time).
Search for "ERROR" to find any shutdown events or config errors.
Note the timestamp of the error relative to startup.
Search for "WARNING" in the 10-20 lines before the error for context.
Check if there's a step loss or position mismatch at the error time.
Review temperature readings in the minutes before the error for thermal anomalies.
If no errors, search for "shutdown" or "restart" to see if the printer was interrupted.
If the issue is intermittent, correlate error timestamps with specific events (e.g., bed heating, tool change, high-speed travel move).

Log analysis is a skill that pays for itself many times over in troubleshooting time saved. The more you read your logs, the more you'll develop an intuition for what looks normal and what signals a developing problem. Make it a habit to check klippy.log after any significant print failure — the answer to "why did this happen" is almost always in there somewhere.