Troubleshooting

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

Sign-in & account issues

GRBL Server works without an account, so none of these stop you engraving — they only affect the AI assistant included with GRBL Server.

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 GRBL Server website"

The host couldn't talk to this website to sign in or check 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.
Everything else in GRBL Server keeps working in the meantime; the Account page shows the last answer it had.

An older version shows a lockout screen

Versions of GRBL Server from before it became free locked every page when the free month ended. GRBL Server is free now, so the website unlocks every copy:

Click Re-check licence on the lockout screen — or Start your free month, if it shows the welcome screen. The app unlocks straight away, and nothing on your computer has been deleted.
Then install the latest version, which has no lockout at all.

GRBL Server won't open

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

Check the notification area first. Closing the window leaves the app running next to the clock, and starting it again just brings that window back. If you see the icon there, click it — that is the running copy.
If the window opens but stays blank, the Microsoft Edge WebView2 runtime — which draws the interface — may be missing or damaged. Re-run the GRBL Server installer; it installs the runtime when it isn't present.
Open Task Manager → Details and look for an existing GRBL Server.exe process. End it before launching again — only one copy can run at a time.
A busy port won't stop the server from starting: it picks a free port automatically (see Port selection). If you pinned a port, switch it back to Automatic in Settings → General and restart.
The log files in %LOCALAPPDATA%\GRBL-SERVER\storage\logs record why it stopped — attach them when you contact us.

The app works on the host, but other computers can't connect

Start with the Network access page on the host — its If the other computer cannot connect section checks most of these for you.

Windows Firewall. Network access shows whether GRBL Server is allowed through; if not, click Allow GRBL Server through the firewall to add the rule for every network type.
Same network. Both computers must be on your main network — the same router, by cable or Wi-Fi. Guest or visitor networks deliberately keep computers from seeing each other.
A VPN on the other computer sends its traffic off your local network, so it never reaches the host. Disconnect it and try again.
The address changed. The router can hand the host a new address after a restart, and an automatic port can change too. Type the address exactly as Network access shows it now, including any port, and don't use localhost or 127.0.0.1 — those point at the computer you're typing on. Reserving a fixed address in the router and pinning the port keeps a bookmark working.
Routers with AP isolation / client isolation, and many corporate networks, block traffic between devices. Turn the setting off or talk to whoever runs the network.
Using the grblserver.local name rather than the IP? That name doesn't work everywhere — see below.

grblserver.local doesn't open the server

The grblserver.local address is a convenience that depends on mDNS, which isn't available on every device or network. The IP address on the host's Network access page always works — reach for it first whenever the name gives you trouble.

Not every computer resolves it. Windows and macOS do without setup; a Linux machine without Avahi doesn't.
Add the port. A browser opening grblserver.local with no port assumes port 80 — usually right. If Network access 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.
Firewall. The name is answered by GRBL Server itself. Running GRBL Server as administrator once lets it add a firewall rule for it on every network profile.
Give it a moment. Right after the server starts it can take a few seconds before the name resolves. If Network access says name announcement isn't active, use the IP.

My USB machine isn't found

Install the right USB-to-serial driver:
- Most inexpensive 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.
On Machines → Add machine, set the connection to USB / Serial and click Search for machines. The board's COM port should now appear.
Close any other program (LightBurn, LaserGRBL, OpenBuilds CONTROL) that might be holding the COM port — only one program can use a serial port at a time.
Check the Baud rate. Most GRBL boards use 115200; if yours was set differently, match it.
Try a different USB cable. Charge-only cables are surprisingly common and silently fail to show up as a serial device.
Already added the machine, and it's now Not connected after you moved it to another USB socket? Click Check again — GRBL Server finds it on its new port by its serial number.

My Wi-Fi / Ethernet controller won't connect

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

Check the mode. If the controller is broadcasting its own Wi-Fi (something like GRBL_ESP32-XXXX or FluidNC), 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. FluidNC, GRBL-ESP32 and ESP3D boards serve it on 81 unless you changed it — Settings → WiFi / Ethernet → port has to match.
Search comes up empty? Set subnet in Settings → WiFi / Ethernet to your network's range, or type the IP and click Look it up.
Power-cycle the controller. WebSocket sessions on small controllers sometimes wedge after a network blip.
Make sure the controller's firmware serves a WebSocket — GRBL Server connects to network controllers over WebSocket only.
If your router has AP isolation / client isolation enabled, Wi-Fi controllers can't be reached from other devices. Disable it in the router's settings.

Machine is in an alarm state

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

Run Home from the machine controls (on Machines, in the Job Station, or on a workflow run). That's the usual way to clear an alarm.
If you know it's safe (the head is clear, nothing is on the limit switches), press Unlock ($X) to clear the alarm without homing.
Still stuck? Press Reconnect in the machine controls, or power-cycle the controller.

A job goes off the edge of the work area

Check the machine's work area in Machines → Settings. The job editor and the Job Station use it as the bed.
Check the engraving profile's Scale and Units. A drawing read in the wrong units comes out 25.4× too big or too small.
Check the profile's start & end G-code — a stray G92 shifts the origin for the whole job. (A relative-mode switch, G91, no longer carries in: every job is put back in absolute mode after its start G-code.)

A workflow won't compile

Open the workflow and read the Problems panel. It lists everything that would stop it compiling — an unconnected Files input, a Job without a profile, a missing value — and names the node.
A value is required. Values marked Required must be given an answer in the compile dialog.
A query placeholder has no value. Every {{name}} in a Database query needs a wire or a value; the error names the node and the placeholder.
The query matched no rows. That's reported as such — there was simply no work to do. Check the query with Test query.
A column is missing. The error lists the columns the query did return; pick the right one as the column that holds the file.
Compiled to nothing = the sources returned no files. Check the name filters and the folder, and use Show the files it finds on the source node.
A Machine commands node failed because its macro is missing, is set for other firmware than the job's machine, or uses a value the job doesn't have. The error says which.

The workflow assistant doesn't answer

"Set up the assistant first" — choose who answers in Settings → AI assistant. The Included with GRBL Server provider needs the free month or a subscription: start the free month, or sign in, on the Account page.
"The included assistant needs a GRBL Server subscription" — the free month has ended, or the subscription lapsed. Subscribe on the website, then click Check now on the Account page; or pick another provider and add your own API key.
"You have used this month's AI assistant allowance" — the included allowance renews on the 1st of next month. To keep going now, pick another provider and add your own API key.
With your own key, click Test the connection in Settings → AI assistant: it says whether the key works and the model can use tools.
"Your next message starts a new conversation" on an old conversation means the provider or the database setup changed since it was held. Carry on — the new conversation sees the workflow as it is now.

A database query returns nothing

Check the connection details in Settings → Database (engine, host, port, user, database).
Going through an SSH tunnel? The error says why the login failed — a refused key, an unknown host. Host and Port are the database's address as the server sees it, usually 127.0.0.1 and 3306. If the server was rebuilt and its identity changed, the tunnel is refused on purpose — once you're sure the change is yours, delete %LOCALAPPDATA%\GRBL-SERVER\data\ssh_known_hosts and the new identity is remembered on the next query.
Test the query directly in your database client first — paste the SQL and check that it returns rows — then with Test query on the node, which shows the first rows without changing anything.
If the query has {{placeholders}}, test it with the same answers the run will use.

The machine moves but the laser doesn't fire

Check the controller is in laser mode: on GRBL, $32=1 (use Show settings in the machine controls to see it).
Check the engraving profile's Laser-on command: M4 (dynamic, the default) or M3 (constant). Some boards only accept one.
Check the machine's Max power (S value) matches $30 on the controller. If the machine expects S1000 but is set to 255, every job burns at a quarter of the power you asked for.
Check the profile's start & end G-code and the G-code before each design — a stray M5 keeps the laser off.
Try a known-good test file from another sender to rule out hardware issues.

Where's my data?

GRBL Server keeps its data in two places on the host:

%LOCALAPPDATA%\GRBL-SERVER\

data\grblserver.db — machines, engraving profiles, job templates, macros, workflows, jobs and runs (SQLite).
data\conf.json — settings (port, network search, database and cloud storage connections, etc.).
storage\jobs_records\ — each job's G-code.
storage\workflows\ — compiled workflow output.
storage\logs\ — log files.

Documents\GRBL-SERVER\local_folder\

Your Library — one subfolder per Library folder. Open in File Explorer in a folder's menu takes you there.

Copying both folders before a big upgrade is a good idea. Restoring them to a fresh install gets you back exactly where you were.

Still stuck?

The contact form and [email protected] go straight to the team that builds GRBL Server. Useful things to include:

Your machine, its firmware and version, and how it's connected (USB, or Wi-Fi / Ethernet).
What you ran (workflow name, job template, file).
What you expected, and what happened.
The log files from %LOCALAPPDATA%\GRBL-SERVER\storage\logs.

Something unclear or wrong on this page? Contact support — these docs improve fastest from real questions.