GRBL Controller Error Code Troubleshooting

Start With the Message Type

Before changing settings, record the complete response shown by the sender. A line such as error:33, ALARM:1, or Grbl 1.1h ['$' for help] provides different information. Reconnecting and repeating the same command may help distinguish a repeatable g-code problem from a possible serial connection or power issue.

Common GRBL Error Codes

error:1 and error:2: invalid or unsupported g-code

These errors commonly appear when a sender transmits a command the installed GRBL version does not understand. Possible causes include unsupported canned cycles, probing commands, macros written for another controller, or post-processor output intended for a different CNC control. Confirm the firmware version shown at connection, then choose a GRBL-compatible post-processor. If you are diagnosing a file, inspect a copy with advanced commands temporarily removed and use only safe, basic motion commands according to the machine manual.

error:3: invalid statement

This generally means the line contains malformed syntax, an invalid letter-number combination, or a value GRBL cannot parse. Look for missing numbers after words such as G, X, F, or S; duplicated commands; unsupported punctuation; and incorrectly formatted comments. Open the file in a plain-text editor and inspect the exact line reported by the sender. This is a useful starting point for readers whose sender identifies a specific rejected line; it will not diagnose wiring or machine-state issues by itself.

error:20 through error:22: invalid or missing values

These errors often result from a command that requires a parameter but received none, or from a value outside the controller's accepted range. A feed-rate command needs a numeric value, and a spindle-speed command needs a value appropriate to the configured spindle-control mode. Check whether the CAM software is outputting decimal notation, units, and axis words in the expected form. If the file was generated for another controller, correcting the post-processor may be more appropriate than editing many lines manually.

error:33: motion target cannot be executed

This is commonly associated with a motion command that conflicts with the current machine state, coordinate system, or configured limits. It may occur when a file requests movement beyond a soft limit, uses an invalid arc, or relies on a work offset that was not established. Verify the active coordinate system, confirm the work zero, and inspect arc commands for incorrect radius or center-offset data. Re-post-processing the file with the correct machine profile is often more practical for readers using a CAM-generated program than attempting many manual edits.

Common GRBL Alarm Conditions

Alarms should not be cleared blindly. They may indicate that the controller has lost its known machine position or detected a condition that could cause a crash. Readers troubleshooting an alarm should identify its cause before attempting to resume motion.

• ALARM:1: hard-limit event or equivalent limit input detection. Inspect limit switches, wiring, connector seating, electrical noise, and the $21 setting. This check is especially relevant when the alarm appears without an expected move to a limit.
• ALARM:2: soft-limit condition. Check homing status, machine coordinates, travel settings such as $130, $131, and $132, and whether the file exceeds configured travel. This is most relevant when an otherwise valid move approaches or exceeds the machine's defined travel.
• ALARM:3: reset during motion or while the controller was not in a valid idle state. Investigate emergency-stop operation, USB interruptions, and power stability; this guidance suits cases involving an unexpected reset rather than a rejected g-code line.
• ALARM:4: probe failure or probe input state problem. Check the probe circuit, workpiece contact, and whether the probing command matches the sender's expectations. This applies to users diagnosing a probing cycle, not to ordinary file parsing errors.
• ALARM:5: homing failure. Confirm that switches trigger individually, axes move toward the switches, and homing direction and pull-off settings are appropriate. Use this path when the alarm occurs during homing.
• ALARM:8: homing was requested while the controller was not ready for the cycle. Reset, release any active hold or alarm state, and retry only after verifying that the machine is clear.

A Controlled Troubleshooting Process

1. Make the machine safe. Stop the sender, switch off the spindle or router, and keep clear of moving parts. Follow the machine manual for emergency-stop and power-isolation procedures.
2. Capture the evidence. Record the complete error, alarm, g-code line, firmware response, sender name, and whether the problem occurs during jogging, homing, probing, or file execution.
3. Separate software from hardware. Send a simple status request, inspect settings with $$, and use the machine manual's procedure for any low-speed jog or motion check.
4. Check configuration. Review steps per millimeter, maximum travel, maximum rate, acceleration, limit polarity, homing enablement, units, and invert settings. Change one setting at a time and record the original value.
5. Inspect physical connections. Check USB strain, controller power, limit-switch connectors, probe leads, motor plugs, shielding, and cable routing. Keep noisy spindle or router wiring separated from signal wiring where practical.
6. Retest cautiously. If the machine manual allows it, use a short, simple motion program with the tool clear of the workpiece. Confirm repeatable behavior before reconnecting the workpiece or running a long program.

Sender, USB, and Configuration Checks

Different sender applications may display, filter, or generate commands differently. Confirm that the selected serial port and baud rate match the controller, and avoid opening the same port in two applications. If the controller resets when the spindle starts, possible causes include electrical interference or a power-distribution issue. A shorter, well-secured USB cable and physical separation from spindle wiring may help, but do not treat this as a substitute for following the machine's electrical instructions.

Back up the settings before changing them. The $$ report is useful for comparison, while $G shows active parser modes on supported versions. After firmware replacement or controller-board changes, do not assume old settings remain valid. Verify axis order, steps per millimeter, travel limits, homing direction, and spindle-control behavior before cutting. This advice is intended for readers changing a board or firmware; it is not a substitute for the exact board documentation.

Trade-offs and Limitations

GRBL is compact and widely supported, but it is not identical across all boards. Some controllers use modified firmware, different limit circuitry, integrated drivers, or sender-specific features. A fix for a standard GRBL 1.1 controller may not apply to a vendor fork. Reflashing firmware can resolve compatibility problems, but it can also erase board-specific settings and create new pin-mapping or spindle-control issues. Use the exact board documentation whenever available; this is particularly important for readers working with a vendor-modified controller.

Software limits improve protection only when machine coordinates are trustworthy. Hard limits provide a separate electrical stop path, but they can be sensitive to noise and mechanical switch quality. For probing, confirm the probe input electrically and use conservative travel settings. For any safety-related uncertainty, stop and consult the manual and applicable local requirements.

Practical Checklist

• Record the exact error:n or ALARM:n response.
• Confirm the installed GRBL version and controller-board model.
• Check the g-code line and the active modal state.
• Verify sender port, baud rate, post-processor, and units.
• Back up $$ settings before making changes.
• Consider jogging, homing, probing, and file execution as separate troubleshooting paths.
• Inspect limit, probe, motor, USB, and power connections.
• Never clear an alarm until its likely cause is understood.

Who This Guide Is For

This guide is intended for desktop CNC owners, makers setting up GRBL-compatible routers, and users diagnosing failures in senders such as Candle or Universal G-code Sender. It is most useful when the controller connects successfully but rejects commands, enters alarms, loses position, or behaves inconsistently during homing and file execution. The code-focused sections suit readers whose sender identifies a rejected line; the alarm and connection sections help readers investigating machine state or communication symptoms.

How This Guide Was Researched

The troubleshooting flow was assembled from commonly documented GRBL error and alarm conventions, sender communication behavior, controller configuration practices, machine-manual guidance, and recurring discussion of homing, limits, probing, serial communication, and g-code compatibility. Marketplace listings and supplied specifications were compared where relevant, but no physical products were tested. Boards and firmware forks differ, so this guide does not treat any marketplace listing, undocumented modification, or single sender application as authoritative.

FAQ