Skip to content

Troubleshooting

Jump to bottom
francis edited this page Oct 14, 2025 · 1 revision

Troubleshooting

This guide helps you resolve common issues with ncSender and your CNC machine.

Troubleshooting Overview Screenshot: Common troubleshooting areas in ncSender

Connection Issues

Can't Find USB Port

USB Port Issues Screenshot: USB port selection showing no ports available

Symptoms:

  • USB port dropdown is empty
  • Port doesn't appear in list
  • "No ports available" message

Solutions:

  1. Unplug and replug USB cable

    • Wait 5 seconds
    • Replug cable
    • Click refresh in port dropdown

  2. Check USB drivers (Windows)

    • Open Device Manager
    • Look for unknown devices or warnings
    • Install CH340, FTDI, or CP2102 drivers as needed
    • Restart computer after driver installation

  3. Avoid Bluetooth ports (macOS)

    • Don't select ports with "Bluetooth" in the name
    • Look for /dev/tty.usbserial-* or /dev/cu.usbserial-*
    • Try different USB port on computer

  4. Check permissions (Linux)

    sudo usermod -a -G dialout $USER
sudo chmod 666 /dev/ttyUSB0
    • Log out and back in
    • Retry connection

  5. Try different USB cable

    • Ensure cable supports data (not power-only)
    • Try shorter cable
    • Test cable with another device

Connection Fails

Symptoms:

  • "Connection failed" error
  • Timeout messages
  • Connected but no response

Solutions:

  1. Verify baud rate

    • Default: 115200
    • Must match controller configuration
    • Try common rates: 115200, 57600, 38400

  2. Check controller power

    • Controller LED should be on
    • Power supply connected
    • Adequate power supply (check voltage/amperage)

  3. Ethernet troubleshooting

    • Ping controller IP: ping 192.168.1.100
    • Verify port number (usually 23)
    • Check firewall settings
    • Ensure both devices on same network
    • Try static IP if using DHCP

  4. Power cycle controller

    • Turn off controller
    • Wait 10 seconds
    • Turn back on
    • Retry connection

  5. Check for other software

    • Close other CNC software
    • Only one application can connect at a time
    • Check for background processes

Connection Drops Randomly

Symptoms:

  • Connection lost during operation
  • Intermittent disconnections
  • "Connection lost" messages

Solutions:

  1. USB cable quality

    • Use shielded USB cable
    • Keep cable away from spindle/VFD
    • Use ferrite beads on cable
    • Try shorter cable

  2. Electrical interference

    • Separate controller from spindle/VFD
    • Ground controller properly
    • Use shielded cables for all wiring
    • Check for loose connections

  3. Power supply issues

    • Verify adequate amperage
    • Check for voltage drops
    • Use dedicated power supply
    • Add power filtering if needed

  4. Computer power management

    • Disable USB selective suspend (Windows)
    • Prevent sleep mode during operation
    • Disable power saving on USB ports

USB Power Settings Screenshot: Disabling USB power management

Machine Control Issues

Machine Won't Move (Alarm State)

Alarm State Screenshot: Machine in alarm state with unlock button

Symptoms:

  • Red "Alarm" status
  • Jog controls disabled
  • "Machine locked" messages

Solutions:

  1. Check alarm code in console

    • Look for "Alarm:X" message
    • Identify cause (see Alarm Codes below)

  2. Unlock machine

    • Click "Unlock" button in toolbar
    • Or send $X from console
    • Only unlock if you've fixed the cause

  3. Common alarm causes:

    • Hard limit triggered: Jog away from limit
    • Soft limit exceeded: Reset or adjust limits
    • Probe failed: Check probe connection
    • Homing failed: Check limit switches

Homing Required

Homing Required Screenshot: "Needs Homing" indicator

Symptoms:

  • "Homing Required" or "Needs Homing" message
  • Some operations disabled
  • Warning in interface

Solutions:

  1. Perform homing

    • Long-press (1 second) Home button
    • Wait for all axes to home
    • Verify completion

  2. Check limit switches

    • All switches properly wired
    • Switches trigger when pressed
    • Firmware homing enabled ($22=1)

  3. Disable homing requirement (not recommended)

    • Only if machine has no limit switches
    • See Current Limitations
    • Consider adding limit switches for safety

Machine Moves Wrong Direction

Symptoms:

  • Jog X+ moves in X- direction
  • Y movements inverted
  • Z goes down when expecting up

Solutions:

  1. Check direction invert settings
    • Settings > Firmware
    • Look for $3 (direction invert mask)
    • Adjust bitmask for affected axes
    • X=1, Y=2, Z=4 (add values to invert multiple)

Direction Invert Settings Screenshot: Firmware direction invert setting

  1. Verify wiring
    • Check motor connections
    • Swap motor phases if needed
    • Consult controller documentation

Machine Moves Too Slow/Fast

Symptoms:

  • Movements slower than expected
  • Rapid moves too fast for comfort
  • Different speed than specified

Solutions:

  1. Check feed rate override

    • Status panel shows feed rate percentage
    • Click to edit (50%-200% range)
    • Reset to 100%

  2. Verify max rate settings

    • Settings > Firmware
    • Check $110, $111, $112 (max rates)
    • Increase if too slow
    • Decrease if too fast/loud

  3. Check acceleration settings

    • $120, $121, $122 (acceleration)
    • Higher values = faster ramping
    • Lower values = smoother movement

  4. Jog feed rate

    • Check feed rate in jog controls
    • Adjust per step size
    • Different for XY vs Z

G-code Issues

G-code Won't Load

Symptoms:

  • Error loading file
  • Blank visualizer after load
  • "Invalid file" message

Solutions:

  1. Check file format

    • Use .nc, .gcode, or .tap extension
    • Plain text file
    • No special characters in filename

  2. Verify file contents

    • Open in text editor
    • Should contain G-code commands
    • Check for corruption

  3. File size

    • Very large files may take time to load
    • Wait for processing to complete
    • Consider simplifying toolpath

Toolpath Looks Wrong

Wrong Toolpath Screenshot: Toolpath appearing incorrect in visualizer

Symptoms:

  • Toolpath position unexpected
  • Scale appears wrong
  • Missing sections

Solutions:

  1. Check units (G20 vs G21)

    • G20 = inches (not supported yet)
    • G21 = millimeters
    • ncSender assumes millimeters
    • Regenerate G-code with correct units

  2. Verify work offset

    • Toolpath shown relative to current offset (G54-G59)
    • Switch workspace if needed
    • Check work zero position

  3. Missing initialization

    • G-code should start with modal states
    • G90 (absolute), G21 (mm), G54 (work offset)
    • Add header to G-code if missing

  4. Arc interpretation

    • Check G2/G3 commands
    • Verify arc mode (G17, G18, G19)
    • CAM post-processor settings

Job Fails Mid-Execution

Symptoms:

  • Job stops unexpectedly
  • Error during run
  • Alarm triggered during job

Solutions:

  1. Check console for error

    • Look for error code
    • Identify problematic line
    • Fix G-code and reload

  2. Soft limit violations

    • Toolpath exceeds machine travel
    • Verify work zero position
    • Check G-code bounds

  3. Feed rate issues

    • F command missing or zero
    • Add feed rate to cutting moves
    • Check maximum feed rate not exceeded

  4. Connection interrupted

    • Check for connection drops
    • See Connection Issues above
    • Restart job from beginning

Probing Issues

Probe Doesn't Trigger

Probe Not Triggering Screenshot: Probe connection test failing

Symptoms:

  • Probe light doesn't activate
  • Connection test fails
  • Machine crashes into probe

Solutions:

  1. Check probe connection

    • Probe plugged into correct port
    • Connection secure
    • No damaged wires

  2. Verify electrical connection

    • Touch probe to grounded metal
    • Probe light should activate
    • If not, check probe/cable

  3. Tool must be grounded

    • Tool/collet must conduct electricity
    • Check tool holder connection
    • Clean tool and collet

  4. Controller probe input

    • Verify controller supports probing
    • Check probe input configuration
    • Test with multimeter if needed

  5. Use connection test

    • Enable in probe dialog
    • Verify probe triggers before starting
    • Prevents crashes

Incorrect Zero Position After Probing

Symptoms:

  • Work zero in wrong location
  • Off by specific amount
  • Inconsistent results

Solutions:

  1. Verify probe type selected
    • 3D Probe vs Standard Block vs AutoZero Touch
    • Must match physical probe

Probe Type Selection Screenshot: Probe type selection

  1. Check probe dimensions

    • Z thickness (height of block)
    • XY thickness (width of edges)
    • Ball diameter (3D probe)
    • Measure accurately

  2. Tool diameter (XY probing)

    • Ensure correct tool diameter entered
    • Affects X and Y calculations
    • Measure tool if unsure

  3. Corner/side selection

    • Verify correct corner selected
    • Match physical probe position
    • Check visualizer shows correct selection

  4. Z-offset calibration

    • Use Z-offset field to fine-tune
    • Compensate for probe wear
    • Test and adjust incrementally

Probing Crashes

Immediate actions:

  1. Hit stop button (center jog button)
  2. Unlock machine if alarmed
  3. Inspect for damage
  4. Identify cause before retrying

Prevention:

  1. Always use connection test for first-time setup
  2. Start with Z-only probing to test
  3. Verify clearances before starting
  4. Reduce rapid movement speed in probe settings
  5. Double-check probe type and dimensions

Performance Issues

Slow Interface

Symptoms:

  • Laggy controls
  • Delayed response
  • Slow visualizer

Solutions:

  1. Close other applications

    • Free up system resources
    • Close unnecessary programs
    • Check CPU/memory usage

  2. Simplify G-code

    • Reduce number of lines
    • Use larger tolerances in CAM
    • Arc fitting instead of line segments

  3. Clear console

    • Large console history affects performance
    • Clear regularly during long jobs
    • Reduce console buffer size

  4. Graphics settings

    • Update graphics drivers
    • Close other GPU-intensive apps
    • Try different view (orthographic vs 3D)

Job Execution Lags

Symptoms:

  • Machine pauses during job
  • Jerky movement
  • Buffer starving

Solutions:

  1. Connection quality

    • Use USB 2.0 or better
    • Quality cable
    • No extension cables

  2. Reduce command frequency

    • Simplify toolpath
    • Increase arc tolerance
    • Use fewer, longer segments

  3. Controller buffer

    • Some controllers have small buffers
    • Reduce feed rate if needed
    • Consider controller upgrade

Application Issues

Application Won't Start

Solutions:

  1. Check installation

    • Reinstall application
    • Verify file integrity
    • Check system requirements

  2. Permission issues

    • Run as administrator (Windows)
    • Check file permissions (Linux/macOS)
    • Allow in security settings (macOS Gatekeeper)

  3. Conflicting software

    • Antivirus blocking
    • Firewall settings
    • Other CNC software interfering

Settings Not Saving

Solutions:

  1. Check permissions

    • Application can write to data folder
    • Not running from read-only location
    • Sufficient disk space

  2. Data folder location

    • macOS: ~/Library/Application Support/ncSender/
    • Windows: %APPDATA%/ncSender/
    • Linux: ~/.config/ncSender/

  3. Backup and reset

    • Export firmware settings
    • Delete settings folder
    • Restart application
    • Reconfigure

Application Crashes

Solutions:

  1. Check logs

    • Look in data folder for log files
    • Note error messages
    • Report to GitHub Issues

  2. Update application

    • Check for latest version
    • Update if available
    • Review changelog for bug fixes

  3. Reset settings

    • Backup current settings
    • Delete settings folder
    • Reconfigure from scratch

Common Error Codes

Error Code Reference Screenshot: Console showing error with explanation

Error:1 - G-code command letter not found

  • Missing command letter (G, M, X, Y, Z, etc.)
  • Check G-code syntax

Error:2 - Missing G-code number

  • Command letter without number (e.g., "G" instead of "G0")

Error:3 - Invalid $ setting

  • Firmware setting doesn't exist
  • Check setting number

Error:9 - G-code locked

  • Machine in alarm state
  • Unlock before sending commands

Error:20 - Unsupported command

  • Controller doesn't support command
  • Check firmware version/features

Error:24 - Jog target exceeds machine travel

  • Soft limits prevent movement
  • Reduce jog distance or adjust limits

Common Alarm Codes

Alarm:1 - Hard limit triggered

  • Machine hit physical limit switch
  • Power cycle controller
  • Jog away from limit
  • Check limit switch wiring

Alarm:2 - Soft limit exceeded

  • Attempted movement beyond configured travel
  • Reset or adjust soft limits
  • Check work zero position

Alarm:3 - Abort during cycle

  • Reset during active job
  • Normal if you stopped job
  • Unlock to continue

Alarm:4 - Probe fail (initial)

  • Probe already triggered at start
  • Move away from probe
  • Check probe wiring

Alarm:5 - Probe fail (no trigger)

  • Probe didn't trigger during cycle
  • Check probe connection
  • Verify probe working (connection test)

Alarm:9 - Homing fail

  • Homing cycle didn't complete
  • Check limit switches
  • Verify homing direction settings
  • Check pull-off distance

Getting More Help

Console Messages

Always check console for:

  • Error codes and descriptions
  • Alarm codes
  • Controller responses
  • System messages

Copy relevant messages when asking for help.

Export Firmware Settings

When troubleshooting:

  1. Settings > Firmware tab
  2. Click Export
  3. Save settings file
  4. Share when requesting support

Report Issues

When reporting bugs:

  • Include ncSender version
  • Describe steps to reproduce
  • Copy console messages
  • Include screenshots if relevant
  • Note operating system
  • Specify controller/firmware type

Community Resources

  • GitHub Issues (when available)
  • GrblHAL documentation
  • CNC forums and communities
  • Controller manufacturer support

Safety Reminders

Before troubleshooting:

  • Power off spindle
  • Remove workpiece if possible
  • Have emergency stop ready
  • Never leave machine unattended
  • Understand alarm causes before unlocking

When in doubt:

  • Stop and assess
  • Don't force through errors
  • Ask for help
  • Better safe than sorry

Related Topics

Clone this wiki locally