How to Debug G-Code: Why Offline Simulation Is the Only Method That Actually Works

There is a moment every CNC programmer knows.

The program is loaded. The setup looks right. The operator's finger is on Cycle Start. And somewhere between confidence and uncertainty, there is a pause — a half-second where everyone in the shop silently asks the same question: is this program actually going to do what we think it's going to do?

That pause is not caution. It is the physical sensation of not knowing.

If your debugging process ends at Cycle Start with that feeling still present, you have not debugged your program. You have decided to find out what happens.

This article is about closing that gap entirely — before the program ever reaches the machine.

What "Debugging G-Code" Actually Means in a Production Shop

In software development, debugging means running code in a controlled environment, observing its behavior, and correcting errors before it reaches users. The key word is before. No software engineer ships code and then watches it fail in production to find out what went wrong.

In CNC machining, the industry has normalized exactly that approach.

The standard debugging workflow — single block mode, dry run, cutting air — is built around running the program on the machine and observing what happens. These methods reduce the probability of a catastrophic outcome. They do not eliminate it. And they do so at a cost that is paid in machine time, operator attention, and production capacity — every single time a new program is proven out.

This is not debugging. It is controlled risk exposure.

Real debugging — the kind that gives you certainty before Cycle Start — happens offline, before the program touches the machine. Everything else is mitigation.

The Standard Methods: What They Do and What They Miss

Single Block Mode

Single block executes the program one line at a time, pausing after each block and waiting for the operator to press Cycle Start again. It forces a slow, deliberate execution that gives the operator time to react.

What it catches: gross positioning errors visible to a trained eye watching the machine move. Wrong axis direction. Obviously incorrect feed rate. A rapid move toward a fixture the operator can see.

What it misses: anything that is not visible from the operator's position, happens too fast to react to, or requires understanding of the full program context to recognize as wrong. A collision between the tool holder and a clamp on the far side of the part. A G41 cutter compensation block that activates in the wrong position. An arc that will alarm out three operations later because the post-processor output the wrong IJK values.

Single block slows the crash down. It does not prevent it.

Dry Run

Dry run overrides the programmed feed rates and executes all moves at a rapid traverse rate, allowing the operator to observe the full motion sequence quickly. On most controls, it also disables spindle rotation and coolant.

What it catches: the general shape of the toolpath — whether the machine is moving in approximately the right direction, hitting approximately the right positions, and not immediately crashing into anything obvious.

What it misses: anything that depends on the actual feed rate (which is overridden), anything that requires the spindle to be running (which it is not), and — critically — anything that only becomes visible when you have a full three-dimensional model of the machine, tooling, fixtures, and workpiece to compare against. A tool holder that clears the part by 2mm at rapid traverse will collide at the correct feed rate due to deflection. A retract move that clears the workpiece but hits the fixture jaw is invisible to an operator watching from the front of the machine.

Dry run shows you the toolpath in broad strokes. It does not show you collisions.

Cutting Air

Cutting air means running the program with the part zero set artificially high — typically 50 to 150mm above the actual workpiece — so the cutter moves through empty space rather than material. It is the most complete on-machine test, because the program runs at actual feed rates with the spindle turning.

What it catches: the full motion sequence in real time, at real speed. Feed rate issues. Spindle direction. Tool change sequences. The general flow of the program.

What it misses: anything that depends on the relationship between the tool and the actual workpiece and fixtures at their real positions. Because the part zero is shifted, the tool is not where it would be in production. Collisions between the tool holder and a clamp that is exactly at the height of the second operation are invisible because the entire program is running 100mm above where it should be. And cutting air ties up the machine completely — for a complex program, this can mean one to three hours of production capacity consumed to prove out a single part.

The Errors That On-Machine Debugging Never Catches

There is a category of errors that none of the above methods reliably detect. These are not edge cases. They are among the most common sources of crashes and scrapped parts in production shops.

Post-Processor Errors

As covered in our article on post-processor problems, your CAM system verifies the toolpath — not the G-code. The post-processor is the software that converts the toolpath into the specific G-code dialect your controller understands, and it introduces its own errors.

Reversed arc directions (G2 output where G3 is correct). Incorrect IJK arc center calculations. Wrong modal state in the opening block. Canned cycle formats incompatible with your controller version. These errors exist in the posted .nc file that will run on your machine, and they are completely invisible inside the CAM simulator because the CAM simulator never reads that file.

Single block, dry run, and cutting air all run the posted G-code. But they rely on a human operator to recognize that an arc is cutting in the wrong direction, or that a rapid move is going somewhere unexpected. When the error manifests as an alarm, the machine has already stopped in the middle of a cut. When it manifests as a collision, the machine has already moved there.

Tool Holder and Fixture Collisions

The tool in your CAM system is usually modeled as a cutting diameter and length. The tool holder — the body, the collet, the flange — is often not modeled at all, or modeled only approximately.

In production, the tool holder is a large, rigid object that occupies significant space above the cutting tool. In deep pockets, on second setups with tall fixtures, or when working around clamps, the holder body clearance is often tighter than the programmer realizes. A tool that has 5mm of clearance at the tip may have the holder body passing through a clamp by 3mm two operations later.

This collision is invisible in CAM simulation if the holder is not modeled. It is invisible in dry run because the operator cannot see the gap between the holder body and the fixture from the control panel. It is invisible in cutting air because the program is running 100mm above the actual fixture position.

It is only visible in a simulation that has a complete three-dimensional model of the machine, spindle, tool holder, cutting tool, fixtures, clamps, and workpiece — all at their real positions — and executes the actual posted G-code against that model.

Tool Length Compensation Errors

G43 (tool length compensation) applies the offset stored in the controller's tool table to the Z-axis position. If the wrong H address is specified, or if length compensation is applied before the tool has moved to a safe Z position, or if the compensation is active during a tool change move, the result is a Z-axis crash.

These errors are not visible in dry run because the compensation values are applied — the machine moves to whatever position the code specifies — and the operator cannot easily verify that the Z position being commanded is the correct one without understanding the full context of the program at that specific moment.

In an offline simulation with the correct tool length data, a wrong H address produces an immediately visible error: the tool appears at the wrong Z position relative to the workpiece, and any subsequent move shows the collision that would result.

What Offline G-Code Simulation Actually Does

An offline G-code simulator is not a CAM backplot. It is not a toolpath viewer. It is a software environment that:

1. Reads the actual posted G-code file — the same .nc or .tap file that will be loaded onto the machine
2. Executes that file against a complete digital model of the machine, including the working envelope, axis travel limits, and controller behavior
3. Simulates the tool holder, cutting tool, fixtures, clamps, and workpiece in three dimensions at their real positions
4. Detects collisions, overtravel, compensation errors, and other conditions that would cause a problem in production
5. Shows the result before the program runs on the machine

The critical distinction is step 1: the simulator reads the posted G-code, not the CAM toolpath. This means post-processor errors are visible. Wrong arc formats trigger the same response they would on the controller. A bad H address produces the same incorrect Z position it would in production.

You are not simulating what you intended the machine to do. You are simulating what the G-code will actually tell it to do.

This is the difference between a CAM backplot and a G-code simulation. One shows intent. The other shows reality.

The Debugging Workflow That Eliminates the Pause at Cycle Start

Offline simulation does not replace on-machine verification entirely. It changes what on-machine verification needs to accomplish.

Without offline simulation: CAM → Post → Load on machine → Single block / dry run / cutting air → Find problems → Fix in CAM → Re-post → Repeat

Every problem is found on the machine, in machine time, with the machine unavailable for production.

With offline simulation: CAM → Post → Simulate offline → Find and fix all problems → Load on machine → First-pass run with confidence

Problems are found at the computer, in minutes, at zero machine time cost. The on-machine first run is not a debugging session — it is a confirmation that what you already verified offline runs correctly on the physical machine.

Single block on the first run still makes sense as a final confirmation. But it runs in a context of certainty, not uncertainty. The pause at Cycle Start disappears because you already know what the machine is going to do.

Not All Simulators Are Equal

Searching for "G-code simulator" returns dozens of tools — free viewers, browser-based backplotters, basic NC viewers. Most of them share the same limitations:

• They are slow. Loading and processing a complex NC program can take minutes. Running a long production program through the simulation takes as long as the program itself. In a shop where time is money, a simulator that is slower than cutting air is not a practical tool — it gets ignored.
• They are difficult to configure. Many require detailed machine kinematic files, controller-specific configuration, or manual parameter setup that demands specialist knowledge just to get started. The programmer who needs to verify a program quickly before a production run does not have time to configure a simulation environment from scratch.
• They are read-only. When the simulation finds a problem — a collision, a bad arc, a wrong retract — the standard workflow is: close the simulator, open the NC file in a separate editor, find the offending line, fix it, save, reload in the simulator, re-run from the beginning. For a long program where the error occurs at operation 6 of 12, re-running from the beginning is painful enough that programmers start skipping the simulation entirely.
• They show toolpath geometry, not machine behavior. Many tools marketed as "G-code simulators" are in practice advanced backplotters — they render the toolpath visually but do not execute the G-code against a real machine model. Post-processor errors, compensation logic faults, and holder body collisions remain invisible.

The result is a category of tools that are technically available but practically unused. They add steps to the workflow without adding enough value to justify those steps. This is one of the main reasons on-machine prove-out remains the default in most shops — not because it is better, but because the alternatives have historically been too slow and too complex to integrate into daily production.

Eureka 3X Pro: Offline G-Code Simulation for Any 3-Axis CNC Machine

Eureka 3X Pro simulates the actual posted G-code against a digital twin of your 3-axis CNC machine — including the complete machine envelope, spindle, tool holder, cutting tool, fixtures, and workpiece.

It is designed to be fast, simple to set up, and practical for daily production use — not a specialist tool that sits unused because it takes longer to configure than to cut air.

Before you press Cycle Start, Eureka shows you:

• Every collision between tool, holder, fixture, clamp, and workpiece
• Incorrect rapid moves that would crash the machine
• Tool length compensation errors
• Arc interpolation problems from post-processor output
• Over-travel conditions
• The complete material removal process, operation by operation

The critical difference from generic simulators: when Eureka finds a problem, you fix it immediately.

You can pause the simulation, edit the NC file directly in the integrated text editor, and resume from exactly the point where you stopped — without restarting from the beginning. Found a bad retract at operation 8 of 12? Fix the line, continue. The corrected program is the file that gets loaded on the machine.

This changes the economics of the workflow. Fixing a problem no longer means exiting the simulator, opening a separate editor, making the change, saving, reloading, and re-running from the top. It means pausing, fixing, and continuing. The total time from "found the error" to "verified the fix" is measured in seconds, not minutes.

The program you load on the machine has already run — in Eureka. Every problem has already been found and fixed. The first physical run is not a test. It is production.

Frequently Asked Questions

Isn't cutting air good enough for proving out a new program? Cutting air is the best on-machine method available, but it has two fundamental limits: it consumes machine time at the same rate as a real first part, and it cannot show collisions that depend on the relationship between the tool and the actual workpiece and fixtures at their real positions. Offline simulation covers both gaps, and it does it before the machine is involved at all.

My CAM system already has a simulator. Why do I need something separate? CAM simulators verify the toolpath — the geometry of the intended cuts. They run before the post-processor and do not read the posted G-code. Errors introduced by the post-processor (wrong arc format, incorrect modal state, bad compensation logic) are invisible in the CAM simulator. An offline G-code simulator reads the actual posted file and catches what the CAM simulator cannot see.

How much time does offline simulation actually save? For a straightforward 3-axis program, a typical on-machine prove-out runs 30 to 90 minutes of machine time. Offline simulation of the same program runs in 5 to 15 minutes at the computer. For complex programs or programs that require multiple prove-out iterations to find all problems, the saving is proportionally larger — and the machine is available for production the entire time.

Does offline simulation require me to model my machine, fixtures, and tooling? Yes — a one-time setup that reflects your actual machine configuration, standard tool holders, and common fixture types. This investment pays back on the first program where a collision is caught offline rather than on the machine. After setup, each new program runs against the existing machine model without additional configuration.

What errors does offline simulation catch that single block mode misses? Any error that requires a complete three-dimensional model to detect: tool holder collisions with fixtures or clamps, post-processor errors in arc output or compensation logic, rapid moves that collide with the fixture on the far side of the part, and Z-axis errors from wrong tool length compensation addresses. Single block slows the machine down. Offline simulation shows you the problem before the machine moves at all.

Is offline simulation relevant for experienced programmers, or just beginners? The errors that offline simulation catches — post-processor arc errors, holder body collisions, compensation logic issues — do not become less likely with experience. They are properties of the code and the machine configuration, not of the programmer's skill level. Experienced programmers benefit from offline simulation because it removes the uncertainty from complex programs, not because they make more mistakes.

The Standard Is Changing

The on-machine prove-out has been the standard in CNC machining for decades because there was no alternative. You could not run the program without the machine.

That is no longer true. Offline simulation runs the program — the actual posted G-code, against a real machine model — before the machine is involved. The uncertainty that lives in the pause at Cycle Start is not an inherent feature of CNC programming. It is a consequence of a workflow that can be changed.

The shops that have changed it do not prove out programs on the machine anymore. They confirm programs on the machine. The difference is everything.