Disclaimer: This is an independent resource site.
Not affiliated with the Voron project or its development team.
<article class="guide-article">
<header>
<h1>Voron Klipper Error Codes Guide</h1>
<p class="lead">Diagnose and fix the most common Klipper errors on your Voron printer.</p>
</header>
<section>
<h2>MCU Errors</h2>
<p>
MCU (Microcontroller Unit) errors are among the most common in Klipper-based Voron printers. These occur when the host computer loses communication with the printer's control board.
</p>
<h3>mcu: Serial Connection Error</h3>
<p>
<strong>Error Message:</strong> <code>mcu 'mcu': Unable to connect</code> or <code>mcu 'mcu': Serial connection error</code>
</p>
<p>
<strong>Root Causes:</strong> USB cable disconnected, wrong serial path in printer.cfg, USB port power cycling, or the MCU is in bootloader mode.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Check physical USB connection at both the Raspberry Pi/SBC and the control board.</li>
<li>Run <code>ls /dev/serial/by-id/*</code> in SSH to verify the serial device is detected.</li>
<li>Update <code>serial:</code> path in <code>printer.cfg</code> to match the detected device ID.</li>
<li>Power cycle the printer — unplug mains power for 30 seconds.</li>
<li>If using a USB hub, try connecting directly to the SBC USB port.</li>
</ol>
<h3>mcu: Timer Too Close</h3>
<p>
<strong>Error Message:</strong> <code>MCU 'mcu' shutdown: Timer too close</code>
</p>
<p>
<strong>Root Causes:</strong> The host sent movement commands faster than the MCU can process. This typically indicates excessive microstepping combined with high speeds, or a host computer that cannot keep up.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Reduce <code>microsteps</code> in your stepper config (e.g., from 64 to 32 or 16).</li>
<li>Lower <code>max_velocity</code> or <code>max_accel</code> in your config.</li>
<li>Check the SBC CPU load with <code>htop</code> — if consistently above 80%, consider a more powerful SBC.</li>
<li>Set <code>max_mcu_stepper_pulse</code> to a lower value (e.g., 100ns instead of 0).</li>
</ol>
<h3>mcu: ADC Out of Range</h3>
<p>
<strong>Error Message:</strong> <code>MCU 'mcu': ADC out of range</code>
</p>
<p>
<strong>Root Causes:</strong> A thermistor reading is outside the valid range (0-1023 on most boards). This usually means a disconnected thermistor wire, a short circuit, or the wrong thermistor type in config.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Check the thermistor wiring for breaks or loose connections at both the board and hotend/bed.</li>
<li>Verify the <code>sensor_type</code> in printer.cfg matches your actual thermistor (e.g., <code>Generic 3950</code> for most Voron builds).</li>
<li>Use a multimeter to check thermistor resistance at room temperature — should be approximately 100k ohms.</li>
<li>Check for short circuits caused by stray wire strands touching the heater cartridge wires.</li>
</ol>
</section>
<section>
<h2>Heater Errors</h2>
<h3>Heater Not Heating at Expected Rate</h3>
<p>
<strong>Error Message:</strong> <code>Heater 'extruder' not heating at expected rate</code>
</p>
<p>
<strong>Root Causes:</strong> The heater cartridge is underpowered, the PID values are wrong, the part cooling fan is blowing on the heater block, or the heater cartridge is partially disconnected.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Run <code>PID_CALIBRATE HEATER=extruder TARGET=245</code> to retune the PID values.</li>
<li>Verify the heater cartridge wattage matches your board's capability (40W for most Voron hotends, 60W for the Bed).</li>
<li>Check that silicone sock is properly installed and not damaged.</li>
<li>Ensure part cooling fan ducts are not directing airflow onto the heater block.</li>
</ol>
<h3>Heater Switched Off</h3>
<p>
<strong>Error Message:</strong> <code>Heater 'extruder' switched off</code> or <code>Heater 'heater_bed' switched off</code>
</p>
<p>
<strong>Root Causes:</strong> Klipper's thermal runaway protection triggered because the temperature exceeded the configured range or dropped unexpectedly.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Check the <code>max_power</code> setting in printer.cfg — ensure it is not limiting the heater.</li>
<li>Inspect the SSR (solid-state relay) for the bed heater if using AC power.</li>
<li>Verify the thermistor is reading correct temperature with a known-good thermometer.</li>
<li>Run PID calibration for both hotend and bed.</li>
</ol>
</section>
<section>
<h2>Probe Errors</h2>
<h3>Probe Z Triggered Before Homing</h3>
<p>
<strong>Error Message:</strong> <code>Probe triggered prior to movement</code>
</p>
<p>
<strong>Root Causes:</strong> The probe is already activated (triggered) when Klipper attempts to home. This can happen if the probe switch is stuck, miswired, or the inductive probe is too close to the bed.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Check if the probe is wired normally-open (NO) vs normally-closed (NC) — Voron builds typically use NC inductive probes.</li>
<li>Verify the <code>pin:</code> setting in the <code>[probe]</code> section has the correct <code>!</code> inversion character.</li>
<li>Check that the probe LED turns off when triggered (metal near).</li>
<li>Adjust the probe Z offset so the probe is not too close to the bed at rest.</li>
</ol>
<h3>Probe Z Endstop Not Triggered During Homing</h3>
<p>
<strong>Error Message:</strong> <code>Endstop 'probe' not triggered during homing</code>
</p>
<p>
<strong>Root Causes:</strong> The probe never made contact with the bed during Z homing. The bed may be too far from the probe, or the probe is faulty.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Manually lower the toolhead and verify the probe triggers when metal is placed under it.</li>
<li>Increase <code>z_position_min</code> or use a thicker washer/spacer under the probe.</li>
<li>Check probe wiring for continuity with a multimeter.</li>
<li>For inductive probes, verify the bed surface is metal (PEI sheets without steel core may not trigger inductive probes).</li>
</ol>
<h3>Probe Samples Exceed Maximum</h3>
<p>
<strong>Error Message:</strong> <code>Probe samples exceed maximum attempts</code>
</p>
<p>
<strong>Root Causes:</strong> The probe is inconsistent between samples, exceeding the configured <code>samples_tolerance</code>. This is common with dirty beds, loose probe mounting, or probe interference.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Clean the bed surface with isopropyl alcohol.</li>
<li>Tighten the probe mounting screws.</li>
<li>Increase <code>samples_tolerance</code> from 0.005mm to 0.01mm.</li>
<li>Reduce <code>samples_retry_dist</code> from 2mm to 1mm.</li>
<li>Check that the probe is not in a magnetic field from the bed heater wires.</li>
</ol>
</section>
<section>
<h2>Endstop Errors</h2>
<h3>Endstop Z / X / Y Not Triggered</h3>
<p>
<strong>Error Message:</strong> <code>Endstop 'x' not triggered during homing</code>
</p>
<p>
<strong>Root Causes:</strong> Mechanical endstop switch is not being pressed during homing, wiring is faulty, or pin configuration is wrong.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Manually trigger the endstop switch and verify the LED lights up (if equipped).</li>
<li>Check the wiring at both the endstop and the board connector.</li>
<li>Use <code>QUERY_ENDSTOP</code> in the console to test endstop status.</li>
<li>Verify the pin assignment and <code>!</code> inversion in printer.cfg.</li>
<li>Check that the endstop is physically positioned so the carriage can reach it.</li>
</ol>
</section>
<section>
<h2>Configuration Errors</h2>
<h3>Option Not Valid in This Section</h3>
<p>
<strong>Error Message:</strong> <code>Option 'xxx' is not valid in section 'yyy'</code>
</p>
<p>
<strong>Root Causes:</strong> A configuration option is placed in the wrong section, has a typo, or is a duplicate.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Check the Klipper documentation for the correct section for the option.</li>
<li>Look for simple typos in both the option name and section header.</li>
<li>Use the <code>CHECK_CONFIG</code> command after making changes.</li>
<li>Remove duplicate option declarations.</li>
</ol>
<h3>Pin is Not Valid</h3>
<p>
<strong>Error Message:</strong> <code>Pin 'xxx' is not a valid pin</code>
</p>
<p>
<strong>Root Causes:</strong> The pin number specified does not exist on the MCU, or uses the wrong naming convention.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Check pin naming convention — BTT boards use <code>PC0</code> format, SKR boards use <code>P1.26</code> format.</li>
<li>Reference your board's pinout diagram.</li>
<li>Ensure you are not using a pin reserved for another function (e.g., a stepper driver pin).</li>
</ol>
</section>
<section>
<h2>Raspberry Pi / Host Errors</h2>
<h3>Klippy Not Connected</h3>
<p>
<strong>Error Message:</strong> <code>Klippy not connected</code> or <code>Unable to connect to Klippy</code>
</p>
<p>
<strong>Root Causes:</strong> The Klippy service is not running, the API socket is blocked, or the process crashed.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Run <code>sudo systemctl status klipper</code> to check the service status.</li>
<li>Check <code>/tmp/klippy_uds</code> exists — this is the Unix domain socket Klipper uses.</li>
<li>Review the Klippy log at <code>~/printer_data/logs/klippy.log</code> for stack traces.</li>
<li>Restart with <code>sudo systemctl restart klipper</code>.</li>
</ol>
<h3>Moonraker Cannot Connect</h3>
<p>
<strong>Error Message:</strong> <code>Moonraker: Cannot connect to Klippy</code>
</p>
<p>
<strong>Root Causes:</strong> Moonraker (the API layer) is running but cannot reach the Klippy Unix socket.
</p>
<p>
<strong>Resolution Steps:</strong>
</p>
<ol>
<li>Ensure Klippy is running first.</li>
<li>Check Moonraker config at <code>~/printer_data/config/moonraker.conf</code> for the correct <code>klippy_uds_address</code>.</li>
<li>Restart Moonraker: <code>sudo systemctl restart moonraker</code>.</li>
</ol>
</section>
<section>
<h2>Quick Reference Table</h2>
<table>
<thead>
<tr>
<th>Error Category</th>
<th>Common Message</th>
<th>Most Likely Fix</th>
</tr>
</thead>
<tbody>
<tr>
<td>MCU Connection</td>
<td>Serial connection error</td>
<td>Check USB cable and serial path</td>
</tr>
<tr>
<td>MCU Timer</td>
<td>Timer too close</td>
<td>Reduce microsteps or speed</td>
</tr>
<tr>
<td>Heater</td>
<td>Not heating at expected rate</td>
<td>Run PID calibration</td>
</tr>
<tr>
<td>Heater</td>
<td>Switched off</td>
<td>Check SSR and thermistor</td>
</tr>
<tr>
<td>Probe</td>
<td>Triggered prior to movement</td>
<td>Check probe pin inversion</td>
</tr>
<tr>
<td>Probe</td>
<td>Not triggered during homing</td>
<td>Lower probe or check wiring</td>
</tr>
<tr>
<td>Endstop</td>
<td>Not triggered during homing</td>
<td>Check switch position and wiring</td>
</tr>
<tr>
<td>Config</td>
<td>Option not valid in section</td>
<td>Check option spelling and section</td>
</tr>
<tr>
<td>Config</td>
<td>Pin is not valid</td>
<td>Check pin naming convention</td>
</tr>
<tr>
<td>Host</td>
<td>Klippy not connected</td>
<td>Restart Klipper service</td>
</tr>
</tbody>
</table>
</section>
</article>