Skip to content

Troubleshooting: 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 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 for mechanical problems on your machine

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: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
  • 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. Disable GCode Clustering in Device Settings, or combining multiple commands into one line.

If you are using Custom GCode, check your settings for accuracy. If you're typing commands in by hand, 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: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
  • If there is an active alarm, fix the problem and try again

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: