Troubleshooting

The most common reasons GRBL Server isn't behaving — and what to try first. If none of these fix it, the feedback form is the fastest way to get help. Include your machine type, connection method, what you ran, and what happened.

Login & licence issues

Try signing in on this website at https://grblserver.com/login with the same credentials. If they don't work here either, reset your password first, then come back to the desktop app.
Make sure caps lock is off — passwords are case-sensitive.

"Could not reach the licensing server"

The host couldn't talk to this website to confirm your account.

From the host, open a browser and try loading https://grblserver.com. If this site doesn't load, it's a network problem (firewall, DNS, captive portal, etc.) — fix that first.
If the host has been working fine until now, you can keep using it for a few more days while you sort out the connection — see below.

All pages redirect me to a "This host is locked" screen

The lockout screen shows up when the licensing server says your account or licence isn't currently valid. The screen itself tells you what's going on, and the recovery is usually one of these:

Expired licence — renew on the GRBL Server website, then click Re-check licence on the lockout screen.
Cancelled licence — re-activate your account on the website, then re-check.
Banned — contact support; an account is normally only banned for a specific reason.
Anything else — click Sign out and sign in again with a valid account.

"This host has been offline too long"

Once a host is signed in, it'll keep working for a few days even if the internet drops. After that, the app politely asks to reconnect before letting you continue.

Reconnect the host to the internet, then click Re-check licence on the lockout screen. The app unlocks immediately.
If you'll be running off-grid for a while (trade shows, remote workshops), let us know — the offline window can be extended on request.

The launcher won't open

Symptom: double-clicking GRBL Server does nothing, or the launcher closes immediately.

Open Task Manager → Details and look for an existing GRBL_SERVER.exe or python.exe process. End it before launching again — only one copy can run at a time.
A busy port is no longer a reason the server won't start: it picks a free port automatically (see Port selection). If you pinned a port manually, switch that setting back to Automatic in Software Settings → Settings → APP and restart.
Check Server logs from inside the UI for the actual stack trace if you can get the UI to load briefly.

I see the UI on the host, but no other device can

Confirm both devices are on the same Wi-Fi network — guest SSIDs are usually isolated from the main one.
Use the host's local IP (e.g. 192.168.1.42, plus a port only if the launcher shows one) on the other device, not localhost or 127.0.0.1 — those resolve to the device you're typing them on.
Allow GRBL Server through Windows Firewall on private networks. If you accidentally allowed only public, remove the rule and let it re-prompt.
If you've got a corporate firewall or AP isolation enabled, that will block client-to-client traffic. Talk to whoever runs the network or move to a router without isolation.
If you were using the grblserver.local shortcut rather than the IP, that name doesn't work on every device — see below.

grblserver.local doesn't open the server

The grblserver.local address is a convenience that depends on mDNS, and mDNS isn't available on every device or network. The IP address shown in the launcher always works — reach for it first whenever the name gives you trouble.

On Android it never works. Android has no .local name resolver — use the host's IP address on Android phones and tablets.
Add the port. A browser opening grblserver.local with no port assumes port 80, which is the default — so usually the bare name is enough. If the launcher shows a port, include it: grblserver.local:8080.
Multicast-blocking networks. Many guest networks, and routers with "AP isolation" or IGMP snooping, drop the multicast traffic mDNS needs. The IP address still works on these — the name won't.
Firewall. The name is answered by GRBL Server itself. Running GRBL Server as administrator once lets it add a firewall rule covering every network profile; until then Windows may block the lookup.
Give it a moment. Right after the server starts it can take a few seconds before the name is resolvable. If it fails immediately after launch, wait and retry.

My USB-serial machine isn't detected

Install the correct USB-to-serial driver:
- Most cheap GRBL boards use a CH-340 chip. Download and install its driver from the chip maker's official driver page if Windows doesn't load one automatically.
- Older boards use FTDI or CP210x. Install from the chipmaker's site.
Open Configuration → Machines → Add Machine, set the transport to USB serial, and click Scan now. The COM port should now appear in the list.
Close any other sender app (LightBurn, LaserGRBL, OpenBuilds CONTROL) that might be holding the COM port — only one program can own a serial port at a time.
Try a different USB cable. Cheap charge-only cables are surprisingly common and will silently fail to enumerate as a serial device.

My WebSocket (Wi-Fi) controller won't connect

Most GRBL32 controllers use the ESP32 chip, which can run in either AP or STA mode. GRBL Server can only reach controllers running in STA mode on the same local network. By far the most common reason a WebSocket machine "won't connect" is that the controller is still in its default AP mode.

Check the mode. If you can see the controller broadcasting its own Wi-Fi (something like GRBL_ESP32-XXXX), it's still in AP mode. Switch it to STA mode and join your workshop Wi-Fi — see Switching the controller to STA mode.
Open cmd.exe on the host and run ping <controller-ip>. If ping times out, the controller isn't reachable on this network — fix that before touching GRBL Server.
Check the WebSocket port. ESP32 GRBL builds usually serve it on 81, not 80 — whatever port the controller uses, Software Settings → Settings → SOCKET → port in GRBL Server has to match it.
Power-cycle the controller. WebSocket sessions on small MCUs sometimes wedge after a network blip.
Confirm the controller's firmware version actually exposes WebSocket. Some ESP32 builds expose Telnet only — if so, add the controller with the TCP transport instead (see Add a TCP machine).
If your router has AP isolation / client isolation enabled, controllers on Wi-Fi can't be reached from wired clients (or even from other Wi-Fi clients). Disable that setting in the router admin panel.

My TCP / Klipper machine won't connect

Check the port. The add-machine page pre-fills it from the protocol — Smoothieware 23, Klipper (Moonraker) 7125, ser2net 8888 — but if your setup differs you have to set the right one. A port checker (or telnet <host> <port>) confirms whether it's open.
For Klipper, GRBL Server talks to Moonraker, not Klipper directly. Make sure Moonraker is running and reachable, and that its [authorization] config lets the GRBL Server host in.
TCP machines aren't auto-discovered — add them with Find by endpoint, not the scan.
A firewall on the controller's host can silently drop the connection. Confirm the port is reachable from the GRBL Server host specifically.

Machine is in an alarm state

A red Alarm state usually means a limit switch was triggered or the controller booted into alarm mode after power-on.

Run a homing cycle from the Job station view. That's the canonical way to clear most alarms.
If you know it's safe (the head is clear, nothing is on the limit switches), you can send $X from the macros / manual command box to force-clear the alarm.
Open the machine's Control dialog and use the reset button to reconnect the controller. The D&R button on the Machines page only refreshes the saved connection status.

A job in the pre-visualizer goes off the bed

Re-check the working area on the machine (Configuration → Machines → EDIT). The pre-visualizer uses this as the bed.
Check the interface's scale parameter. If you imported an SVG in inches but the interface assumes mm, you'll get a 25.4× job.
Check the sequence's start G-code — a stray G92 or absolute/relative-mode switch (G90 / G91) inherits into the job.

A workflow won't compile

Open the workflow and look for nodes outlined in red. Hovering over a red socket usually surfaces the reason (incompatible type, missing required input, exclusivity violation).
If a Setup job node has both preset and interface connected, that's invalid. Pick one.
If a Setup job has both mediator and local folder connected, that's also invalid. Pick one source.
Compile to nothing = the file source returned 0 files. Check filename filters (prefix/suffix/extensions) and the source folder/query.
Check Server logs for the Python stack trace if the editor shows a generic error.

A mediator query returns nothing

Test the query directly in your database client first — paste the SQL and check that it returns rows.
Mediator queries support {param} placeholders that are injected at run time. If your query has placeholders, every placeholder must be supplied by the workflow.
The mediator expects an SVG content column by default. If the column is named differently, configure the column mapping on the mediator.

The machine moves but the laser doesn't fire

Check the interface's laser mode: constant burn uses M3, dynamic uses M4. Some boards only accept one; others need $32=1 in the controller settings to enable laser mode.
Check the sequence. If it ends with M5 (laser off) and your interface doesn't re-issue M3/M4, the laser stays off.
Try a known-good test G-code from a different sender first to rule out hardware issues.

Where's my data?

Everything you create lives in:

%USERPROFILE%\Documents\GRBL-SERVER\

data/grblserver.db — machines, presets, workflows, interfaces, jobs, runs (SQLite).
data/conf.json — server config (port, log level, file extensions, etc.).
local_folder/<group>/ — local-folder files.
storage/workflows/workflow_<id>/<timestamp>/ — compiled workflow output.
storage/jobs_records/ — per-job G-code and logs.
storage/logs/ — server logs.

Copying this folder before a big upgrade is a good idea. Restoring it to a fresh install gets you back exactly where you were.

Still stuck?

The feedback form goes straight to the maintainer. Useful things to include:

Machine type, firmware version, and connection (serial / Wi-Fi / TCP).
What you ran (workflow name, job preset, file).
What you expected, what happened.
Relevant section of the Server logs (Storage → Server logs) — copy the last 20-30 lines, or use Download there to grab the whole file.

Something unclear or wrong on this page? Tell me — beta docs improve fastest from real questions.