Skip to content

GRBL Errors

GRBL devices have a number of different alarms and error codes you may encounter. These will be visible in the Console window.

This page contains information about the errors and alarms LightBurn users are most likely to encounter, as well as some other frequently encountered problems with GRBL devices. For additional information, we've found the following resources helpful:

Official GRBL Documentation

DomoticX's GRBL Error List

GRBL Alarm Codes

Alarms are emergency messages, and are used when something has gone very wrong. These are shown in the Console window as ALARM:#, with a number to tell you what caused the alarm.

ALARM:1

A limit switch was triggered while the machine was moving. The machine position is probably lost, which causes the machine to hit the edges of its workspace.

Fix this alarm by rehoming the machine. If this continues to happen:

  • Review your Start From and Job Origin selection, and make sure you are not commanding the laser to move outside of its physical bounds. See Coordinates and Job Origin.
  • Make sure your machine is homing correctly by comparing the position shown in the Move window in LightBurn to the machine's actual position within its work area.
  • Some limit switches are triggered by reading resistance to stepper motors. Make sure the wires aren't snagging and causing a false trigger, and check your machine for mechanical problems.

ALARM:2

You're trying to send the machine outside of its known working area, and GRBL has prevented this to prevent damage to the machine. This can happen for several reasons:

  • You're trying to run a job that exceeds the size of the machine work area.
  • You're trying to run a job in Current Position or User Origin mode and haven't properly set the Job Origin or User Origin settings. See Coordinates and Job Origin.
  • You're working with a Y axis rotary and the distance you are commanding the rotary to travel exceeds the Y axis max travel limit set in your laser's firmware. Temporarily disable Soft Limits in the Machine Settings window, or by entering $20=0 in the Console window. Be sure to re-enable Soft Limits when returning to flat engraving.
  • You have your machine misconfigured, possibly trying to run a negative workspace machine without a workspace offset. See Common GRBL Setups.

ALARM:3

The laser halted abruptly, sometimes due to another Alarm or Error, or, often, the computer losing connection to the machine. Rehome the machine to ensure the machine reports its coordinates correctly. See Connection Troubleshooting for help if this happens repeatedly.

ALARM:8

The machine failed to pull off one or both limit switches after homing.

  • Inspect your laser's limit switches to make sure they are not stuck in the closed position.
  • Check your machine's belt tension and overall mechanical setup to make sure it is capable of moving, homing properly, and clearing the limit switches. See Troubleshooting: Mechanical Issues for more information.
  • Make sure your power supply is securely plugged in and functional. A USB connection can sometimes be enough to power a laser's control board, but it will not provide enough power for the stepper motors to move off the limit switches.

ALARM:9

The machine's attempt to home failed because it didn't locate a limit switch. GRBL will stop homing to prevent potential damage to the machine if it doesn't encounter a limit switch within 1.5x the maximum travel distance.

  • Make sure your machine has limit switches. If you installed them yourself, make sure they're wired correctly and the connectors are snug.
  • Check your machine's belt tension and overall mechanical setup to make sure it is capable of moving and homing properly. See Troubleshooting: Mechanical Issues for more information.
  • Make sure your power supply is securely plugged in and functional. A USB connection can sometimes be enough to power a laser's control board, but it will not provide enough power for the stepper motors to respond to the homing command.

GRBL Error Codes

These error codes are less severe than alarm codes, and are used when your machine receives a command it can't act on. Like alarms, these are shown in the Console window as error:#, with a number to tell you what caused the error.

Error:1

The machine received an invalid GCode command. This error code is usually the result of enabling GCode Clustering for a device that does not support it, or combining multiple commands into one line.

Make sure GCode Clustering is disabled in Device Settings.

If you are using Custom GCode, check your settings for accuracy. If you're typing commands in by hand in the Start or End GCode fields under GCode tab of the Device Settings window, check for typos.

Error:3

The machine received the $ system command but does not recognize or support it.

Error:5

LightBurn sent the command to the controller to home it, but the controller does not have homing enabled or configured. Typically, this occurs when Auto-Home On Startup is enabled in Device Settings for a machine without homing switches.

Error:8

A command was sent to your laser while it was still processing another command. If your laser is homing, wait and try again.

This error can also be caused by communications corruptions or electrical interference.

Error:9

LightBurn tried to send a command to your device, but the machine is locked. GRBL locks devices while jogging (moving the gantry) or when the machine has an active GRBL alarm.

  • If the machine is moving, wait for it to finish moving.
  • Enter $X in the Console window to unlock the machine.
  • If there is an active alarm, identify the alarm and address the cause.

Error:20

The machine received an unsupported or invalid GCode command. This is usually the result of the wrong device type being selected.

Tip

To check what version of GRBL your laser is running, enter $I into the Console window and press Enter. The messages shown in response should include the GRBL version in a message starting with VER.

  • Make sure your device type is set correctly. In most cases, your device should be set to GRBL. If your laser is running GRBL 1.1e or earlier, change your device type to GRBL-M3. To check or change your device type:
    • Click the Devices button in the Laser window
    • Double-click your device
    • Change the device type if needed
    • Click Next and then Finish to complete the setup prompts and save the changes
  • If your laser is running GRBL 1.1f or later, and the Error:20 message is accompanied by MSG: M4 requires laser mode or a reversible spindle, enter $32=1 in the Console window and press Enter to enable Laser Mode.

Error:24

The machine received an invalid GCode command, combining two GCode commands that both require X/Y/Z axis parameters. This is usually the result of communications corruption.

Other Common Problems for GRBL Machines

Busy

The Busy bar in the Laser Window is not necessarily an error - it shows that the machine is busy doing something. However, if you are seeing Busy but the machine is not moving, it may not be connected to the computer.

Laser Not Connecting

If you see Disconnected in the Laser Window, your computer is unable to communicate with the laser. Make sure it's plugged in and turned on. If it still does not connect:

For more help using LightBurn, please visit our forum to talk with LightBurn staff and users, or email support.