Troubleshooting
Diagnose connection, output, import, geometry and engraving-quality problems with structured LightBurn troubleshooting steps.
Broken vector import: extra lines, hidden shapes and wrong scale
Determine whether a problem comes from clipping masks, stacked geometry, units or export settings before rebuilding the artwork.
Build a troubleshooting evidence package that another person can use
Collect the file, machine context, screenshots and Console evidence needed to reproduce a laser problem without guessing.
Smoke or soot stains the material surface
Treat flame and accumulating smoke as safety events first, then control extraction, approved air assist, energy and surface protection.
Engraving or cutting strength changes across the work area
Use a position matrix to separate material variation, focus height, bed geometry, optics and beam-path causes.
Bidirectional engraving lines do not align
Check mechanics first, then measure and correct a consistent left/right shift with LightBurn Scanning Offset Adjustment.
Laser output flashes or cuts out during motion
Separate project, GRBL power-scaling, speed, connection and hardware causes when the beam appears only intermittently.
Missing Fonts and Portable LightBurn Projects
Live text depends on installed fonts. Moving a project to another computer can substitute/miss fonts unless the same font exists or text is converted to paths when appropriate.
Fill Missing? Check for Open Paths
Fill requires closed boundaries. A visually almost-closed vector can still be open by a tiny gap and therefore not fill as expected.
Double Lines and Unexpected Double Cuts
Duplicate geometry can come from imports, overlapping shapes, stroked artwork converted to outlines or repeated layers. Preview is the fastest way to confirm repeated toolpaths.
Imported Artwork Has the Wrong Physical Size
Wrong import size is commonly a units/DPI/vector-format interpretation issue, not a steps/mm calibration problem.
Laser Output Stays On or Fires Unexpectedly
Unexpected continuous firing is a safety-critical symptom involving output mode, PWM/TTL wiring, controller state or hardware failure. Stop operation before diagnosis.
Laser Moves but Does Not Fire
Motion with no output can be software-layer Output state, S-value scaling, M3/M4/$32/device type, interlocks, power supply, enable wiring or laser-module hardware.
Intermittent USB Disconnects During a Job
Random disconnects can be caused by cable quality, EMI, grounding/power problems, USB power management, hubs or controller resets. The timing and Console log are diagnostic evidence.
“Connecting…” and “Port opened…”: Host Messages vs Controller Output
Messages such as “Connecting…” are generated by LightBurn/host logic, not GRBL. They describe connection progress and should not be decoded as firmware errors.
GRBL Error:20: Unsupported G-code, Device Type or M4
Error:20 often points to unsupported/invalid G-code. In LightBurn, common causes include the wrong device type or M4 being sent to firmware/configuration that does not support laser-mode behavior.
GRBL ALARM:8 and ALARM:9: Homing Failures
ALARM:8 commonly means a homing switch could not clear during pull-off; ALARM:9 means the expected switch was not found within the configured search distance.
GRBL ALARM:3: Reset During Motion
ALARM:3 indicates a reset occurred while motion was active. Because physical motion may have stopped between known steps, the machine position may no longer be trustworthy.
GRBL ALARM:1: Hard Limit Trigger Diagnosis
ALARM:1 means a hard-limit input triggered during motion; position is likely lost and the cause may be physical travel, switch/wiring behavior or electrical noise.
GRBL ALARM:2: A Full Soft-Limit Diagnosis
ALARM:2 means GRBL predicted a commanded target outside known travel. Common causes include placement/origin mode, incorrect travel configuration, rotary use and coordinate offsets.
GRBL error:N vs ALARM:N — Different Failure Classes
An `error:` usually means a received command/block was rejected, while `ALARM:` signals a controller safety/state condition that can lock motion and sometimes invalidate position.
GRBL Errors and Alarms: Read the Console Before You Unlock Anything
Treat GRBL alarm/error numbers as diagnostic messages and fix the cause instead of reflexively clearing the controller state.
Connection Troubleshooting: USB, Port, Power and 'Connected but Not Responding'
Diagnose connection failures in a safe order before changing firmware or random controller settings.