GRBL Alarm Codes: Complete Troubleshooting Guide
GRBL alarm codes halt your laser or CNC machine when it detects a hardware-level problem—a limit switch trigger, a failed homing cycle, or a move that exceeds the work area. Unlike G-code errors, alarms require you to fix the physical issue before the machine will move again. This guide covers every alarm code from ALARM:1 through ALARM:9 with plain-English explanations, exact console commands, and step-by-step fixes that work with LightBurn, xTool, OMTech, Sculpfun, Atomstack, and any GRBL-based controller.
Quick Reference Table
| Code | Name | Common Cause | Quick Fix |
|---|---|---|---|
| 1 | Hard Limit Triggered | Laser head hit a physical limit switch during movement. | Type $X to unlock, then move the head away from the switch. |
| 2 | Soft Limit Exceeded | A move command tried to travel beyond the configured work area. | Check $130/$131/$132 max travel settings and reposition your job origin. |
| 3 | Reset During Motion | GRBL received a reset signal while the machine was actively moving. | Type $X to unlock, re-home with $H, and check your USB cable. |
| 4 | Probe Fail — Already Triggered | The probe input was already active before the probing cycle started. | Check probe wiring and confirm the probe is NOT triggered when floating. |
| 5 | Probe Fail — Contact Lost | The probe lost contact during the probing cycle. | Check the probe cable connection and reduce the probe feed rate. |
| 6 | Reset During Homing | GRBL received a reset command while a homing cycle was in progress. | Retry homing with $H and check for physical obstructions. |
| 8 | Homing Pull-Off Failed | After touching the limit switch, the machine could not pull away from it. | Check if the limit switch is stuck and adjust $27 (pull-off distance). |
| 9 | Homing Failed — Limit Switch Not Found | The axis traveled its full search distance without finding a limit switch. | Check limit switch wiring, test the switch manually, and confirm $22=1. |
Note: ALARM:7 is not defined in the standard GRBL specification.
ALARM:1—Hard Limit Triggered
What it means
Your machine detected that the laser head physically contacted a limit switch while it was moving. GRBL immediately halts all motion to prevent mechanical damage.
Common causes
- •The laser head traveled past its safe boundary and struck a limit switch.
- •A limit switch is loose or misaligned, triggering unexpectedly.
- •Wiring to a limit switch is damaged, causing a false signal.
- •Debris or material is blocking the gantry near a limit switch.
- •The job origin is set too close to the edge of the work area.
Step-by-step fix
- 1Open the console in LightBurn (or your preferred sender) and type
$Xthen press Enter. This unlocks GRBL. - 2Manually (by hand, with the machine powered) nudge the laser head away from the limit switch it triggered.
- 3Inspect the limit switch on the axis that faulted. Make sure it is firmly mounted and the actuator moves freely.
- 4Run a homing cycle with
$Hto re-establish the machine zero position. - 5Re-run your job with the origin repositioned at least 5 mm away from any axis edge.
Prevention
- ✓Always home the machine (
$H) before starting a job. - ✓Keep limit switches clean and check mounting screws monthly.
- ✓Set soft limits (
$20=1)so GRBL rejects out-of-bounds moves before they happen.
Pro tip
If ALARM:1 keeps firing on the same axis, swap the limit switch with another axis to determine whether the switch itself is faulty or the wiring is the problem.
ALARM:2—Soft Limit Exceeded
What it means
GRBL checked the requested move against your machine dimensions and determined it would exceed the defined boundaries. The move was rejected before any motion occurred.
Common causes
- •The job dimensions plus origin offset exceed the machine work area.
- •$130, $131, or $132 (max travel for X, Y, Z) are set smaller than the actual travel.
- •The work origin was set near the edge of the bed, leaving insufficient room.
- •Soft limits are enabled ($20=1) but the travel values do not match the physical machine.
- •The design was not centered or positioned correctly before sending.
Step-by-step fix
- 1Type
$Xin the console to clear the alarm state. - 2Check your max travel settings: type
$130,$131, and$132in the console and compare with your machine specs. - 3If the values are wrong, update them. For example:
$130=400sets X travel to 400 mm. - 4In LightBurn, reposition the job origin toward the center of the bed so the full design fits within bounds.
- 5Use "Frame" in LightBurn to preview the job boundary before running.
Prevention
- ✓Always use the Frame button to check job bounds before running.
- ✓Verify
$130/$131/$132match your machine manufacturer specs. - ✓Leave a 5-10 mm margin from each axis edge when setting the origin.
Pro tip
In LightBurn, go to Edit > Device Settings and set the correct workspace size. This lets LightBurn warn you visually when a design exceeds the bed.
ALARM:3—Reset During Motion
What it means
While the machine was executing a movement command, the controller received an unexpected reset. This often points to a communication issue between the computer and the controller board.
Common causes
- •A loose or low-quality USB cable caused a momentary disconnect.
- •The computer went to sleep or the USB port lost power briefly.
- •EMI (electromagnetic interference) from the laser power supply disrupted the USB signal.
- •The sending software crashed or was closed during a job.
- •A power fluctuation reset the controller board.
Step-by-step fix
- 1Type
$Xin the console to unlock the machine. - 2Run
$Hto re-home and establish a known position. - 3Replace the USB cable with a high-quality, shielded cable shorter than 2 meters.
- 4Disable USB selective suspend in your computer power settings.
- 5If using a laptop, plug it into wall power during jobs to prevent sleep.
Prevention
- ✓Use a ferrite-core USB cable to reduce EMI susceptibility.
- ✓Keep the USB cable away from the laser power supply and stepper motor wiring.
- ✓Disable all power-saving modes on the connected USB port.
Pro tip
If ALARM:3 happens consistently mid-job, try sending the file via SD card (if your controller supports it) to rule out USB communication entirely.
ALARM:4—Probe Fail — Already Triggered
What it means
GRBL attempted to start a probing cycle (G38.x), but the probe pin was already in a triggered state before any movement began. The cycle cannot proceed because GRBL needs to detect the transition from untriggered to triggered.
Common causes
- •The probe wire is shorted or touching the workpiece before the cycle begins.
- •The probe input pin is wired incorrectly (normally-closed instead of normally-open).
- •A damaged probe cable is creating a constant signal.
- •The controller board probe pin is faulty.
Step-by-step fix
- 1Disconnect the probe cable and check if the alarm clears on the next attempt.
- 2Use a multimeter to confirm the probe circuit is open (no continuity) when the probe is not touching anything.
- 3Inspect the probe cable for bare wires, kinks, or damage.
- 4Verify the probe is wired to the correct pin on your controller (typically A5 on Arduino-based boards).
- 5If the wiring is correct, test with a different probe or cable to isolate the fault.
Prevention
- ✓Store the probe cable coiled and away from sharp edges.
- ✓Test probe continuity before each probing session.
Pro tip
Most GRBL laser setups do not use probing. If you see ALARM:4 unexpectedly, check whether something is accidentally connected to the probe pin on your controller.
ALARM:5—Probe Fail — Contact Lost
What it means
During a probing operation, GRBL detected that the probe signal was lost after initial contact. This usually means the probe bounced or the connection was intermittent.
Common causes
- •The probe tip bounced off the surface during contact.
- •The probe cable has an intermittent connection.
- •The probe feed rate is too fast, causing unreliable contact detection.
- •Vibration from the machine caused the probe to lose contact momentarily.
Step-by-step fix
- 1Inspect the probe cable for loose connectors or damaged insulation.
- 2Reduce the probe feed rate. For example, try
G38.2Z-10 F20 (20 mm/min) instead of a higher rate. - 3Ensure the probing surface is clean and conductive (for conductive probes).
- 4Tighten all probe cable connections and re-run the cycle.
Prevention
- ✓Use a slow feed rate (F10-F30) for probing operations.
- ✓Secure the probe cable so it does not move during the cycle.
Pro tip
If you are using a Z-probe for material height on a laser, ensure the probe plate sits flat on the material. Any wobble will cause intermittent contact.
ALARM:6—Reset During Homing
What it means
The homing cycle was interrupted by a reset signal. This can happen if the homing cycle takes too long (obstruction), the USB connection drops, or the user accidentally sends a reset.
Common causes
- •A physical obstruction prevented the axis from reaching its limit switch in time.
- •The USB connection dropped during the homing sequence.
- •The user or software sent a reset command while homing was active.
- •A power fluctuation reset the controller mid-homing.
Step-by-step fix
- 1Visually inspect all axes for obstructions (debris, loose material, cables in the path).
- 2Manually push the gantry along each axis to confirm smooth, unobstructed travel.
- 3Re-attempt homing by typing
$Hin the console. - 4If it fails again, check USB cable quality and computer power settings.
- 5Verify limit switches are reachable by manually triggering each one and checking the status with
?in the console.
Prevention
- ✓Clear the work area of loose material before homing.
- ✓Use a quality shielded USB cable.
- ✓Ensure no cables snag or block gantry travel.
Pro tip
If homing consistently fails on one axis, manually move that axis to the limit switch location and see if the switch clicks. A switch that does not actuate needs replacement.
ALARM:8—Homing Pull-Off Failed
What it means
During homing, GRBL moves toward the limit switch until it triggers, then reverses a short distance (the pull-off). ALARM:8 means the switch was still active after the pull-off move completed, so GRBL cannot confirm it cleared the switch.
Common causes
- •The $27 pull-off distance is set too small for the switch to deactivate.
- •The limit switch is physically stuck in the triggered position.
- •The limit switch lever or actuator is bent, keeping it pressed.
- •Wiring fault causing the switch to read as permanently triggered.
Step-by-step fix
- 1Check the current pull-off distance by typing
$27in the console (default is often 1.0 mm). - 2Increase it: try
$27=3(3 mm pull-off distance). - 3Physically inspect the limit switch. Press it by hand and confirm it springs back.
- 4If the switch is stuck, clean or replace it.
- 5Re-run homing with
$Hafter making changes.
Prevention
- ✓Set
$27to at least 2.0 mm for reliable pull-off on most machines. - ✓Periodically check that limit switches spring back freely.
Pro tip
On machines with optical limit switches (no physical contact), the $27 value may need to be larger (5 mm+) because the detection zone is wider than a mechanical switch.
ALARM:9—Homing Failed — Limit Switch Not Found
What it means
GRBL moved the axis the maximum allowed homing search distance and never detected a limit switch trigger. Either the switch is disconnected, broken, or wired to the wrong pin.
Common causes
- •The limit switch cable is disconnected or has a broken wire.
- •The limit switch itself is faulty and does not trigger.
- •The switch is wired to the wrong input pin on the controller board.
- •Homing is enabled ($22=1) but no switches are physically installed.
- •The homing search distance ($25) is shorter than the actual axis length.
Step-by-step fix
- 1Type
$22in the console. If it returns 0, homing is disabled. Set$22=1to enable it. - 2Visually inspect the limit switch wiring on the failing axis. Look for disconnected or cut wires.
- 3Manually press the limit switch by hand while watching the console. Type
?to see if GRBL detects the pin change. - 4If the switch does not register, check the wiring diagram for your controller and confirm the signal wire is on the correct pin.
- 5If wiring is correct and the switch still does not register, replace the switch.
- 6Increase the homing search distance if needed:
$25=300(or higher than your axis length in mm).
Prevention
- ✓During initial setup, test every limit switch with the
?status command before enabling homing. - ✓Secure limit switch cables with zip ties so they cannot be snagged.
- ✓Keep spare limit switches available for quick replacement.
Pro tip
ALARM:9 is the most common homing alarm on new laser setups. Before troubleshooting anything else, disconnect and reconnect the limit switch connector on the controller. A loose pin header is the cause more often than a broken switch.
Common GRBL Errors vs. Alarms
GRBL uses two distinct categories of messages to tell you something went wrong, and understanding the difference saves troubleshooting time.
Errors (error:1, error:2, etc.)
Errors are command-level rejections. They fire when GRBL receives a G-code line it cannot parse or execute—like an unsupported command, a missing axis value, or an invalid feed rate. The machine does not move. Fix the G-code and resend.
Alarms (ALARM:1–ALARM:9)
Alarms are hardware-level events that occurred during motion. Something physically happened—a switch triggered, a homing sequence failed, a probe lost contact. The machine locks out until you type $X to unlock and resolve the issue.
If you see error messages instead of alarms, check out our AI laser assistant which can diagnose both error and alarm codes instantly.
Frequently Asked Questions
- What does ALARM:2 mean on my laser?
- ALARM:2 means a soft limit was exceeded. Your laser controller checked the requested move against your configured work area dimensions ($130/$131/$132) and determined the move would go out of bounds. Reposition your job origin toward the center of the bed and verify your max travel settings match your machine.
- How do I clear a GRBL alarm?
- Type $X in the console (LightBurn, LaserGRBL, or any GRBL sender) and press Enter. This sends the unlock command. After unlocking, run $H to re-home the machine so it knows its position. Always fix the underlying cause before re-running your job.
- Why does my laser keep showing ALARM:9?
- ALARM:9 means the homing cycle could not find a limit switch. The most common causes are a disconnected limit switch cable, a faulty switch, or the switch wired to the wrong pin. Test each switch manually by pressing it and checking the GRBL status report (type ? in the console) to see if the input changes.
- What is the difference between GRBL errors and alarms?
- GRBL errors (like error:1, error:2) indicate problems with G-code commands — the controller rejects a line before executing it. Alarms indicate real-time events that happened during motion (hitting a limit switch, failing to home, losing a probe signal). Errors are command-level; alarms are hardware-level.
- How do I reset my laser after an alarm?
- First type $X in the console to unlock the machine. Then run $H to re-home. If the alarm was caused by a physical issue (stuck switch, obstruction), fix that before re-homing. Once homing completes successfully, you can start a new job.
- Can I disable GRBL alarms?
- You can disable specific safety features — for example, $20=0 disables soft limits and $22=0 disables homing — but this is not recommended. These alarms exist to protect your machine from crashes and damage. Instead of disabling them, fix the root cause using the troubleshooting steps above.
Still stuck?
Describe your alarm code, machine model, and what you were doing. Our AI assistant will diagnose the problem and walk you through the fix.
Ask the AI Assistant