Error Codes

Overview

All API functions that can fail return an integer error code. A return value of GCODE_OK (0) indicates success. Any non-zero value indicates an error.

For additional error details, call gcode_get_last_error() to retrieve a human-readable error message.

int result = gcode_connect(handle, "192.168.1.100");
if (result != GCODE_OK) {
    printf("Error %d: %s\n", result, gcode_get_last_error());
}

Error Code Reference

Code	Name	Description
0	GCODE_OK	Operation completed successfully.
1	GCODE_ERR_INVALID_HANDLE	The provided handle is NULL or invalid.
2	GCODE_ERR_NOT_CONNECTED	Operation requires a connection, but not currently connected to a controller.
3	GCODE_ERR_ALREADY_CONNECTED	Attempted to connect when already connected. Call `gcode_disconnect()` first.
4	GCODE_ERR_CONNECTION_FAILED	Failed to establish connection to the controller. Check IP address and network connectivity.
5	GCODE_ERR_PARSE_FAILED	Failed to parse G-code command. The command syntax is invalid or the command is not supported.
6	GCODE_ERR_FILE_NOT_FOUND	The specified file does not exist.
7	GCODE_ERR_FILE_READ_ERROR	Failed to read from the file. Check file permissions.
8	GCODE_ERR_INVALID_ARGUMENT	An invalid argument was provided (e.g., invalid axis letter).
9	GCODE_ERR_PROCESSING_ACTIVE	Configuration method called while G-code processing is active. Stop processing first.
11	GCODE_ERR_TIMEOUT	A wait operation timed out before completing.
12	GCODE_ERR_LICENSE	License validation failed. Ensure a valid license is installed.
13	GCODE_ERR_NOT_FOUND	The requested key was not found in the result. Returned by result accessor functions.
14	GCODE_ERR_TYPE_MISMATCH	The key exists in the result but the value is a different type than requested. Returned by result accessor functions.
99	GCODE_ERR_UNKNOWN	An unknown error occurred. Check `gcode_get_last_error()` for details.

Header Definition

Error codes are defined as preprocessor macros in gcode_api.h:

#define GCODE_OK                    0
#define GCODE_ERR_INVALID_HANDLE    1
#define GCODE_ERR_NOT_CONNECTED     2
#define GCODE_ERR_ALREADY_CONNECTED 3
#define GCODE_ERR_CONNECTION_FAILED 4
#define GCODE_ERR_PARSE_FAILED      5
#define GCODE_ERR_FILE_NOT_FOUND    6
#define GCODE_ERR_FILE_READ_ERROR   7
#define GCODE_ERR_INVALID_ARGUMENT  8
#define GCODE_ERR_PROCESSING_ACTIVE 9
#define GCODE_ERR_TIMEOUT           11
#define GCODE_ERR_LICENSE           12
#define GCODE_ERR_NOT_FOUND         13
#define GCODE_ERR_TYPE_MISMATCH     14
#define GCODE_ERR_UNKNOWN           99

Error Handling Patterns

C Pattern

int result = gcode_connect(handle, ip);
if (result != GCODE_OK) {
    switch (result) {
        case GCODE_ERR_ALREADY_CONNECTED:
            // Already connected - may be okay
            break;
        case GCODE_ERR_CONNECTION_FAILED:
            fprintf(stderr, "Cannot reach controller at %s\n", ip);
            return -1;
        default:
            fprintf(stderr, "Connection error %d: %s\n",
                    result, gcode_get_last_error());
            return -1;
    }
}

C++ Pattern

// Using error callback for runtime errors
gcode.SetOnError([](int code, const char* cmd, void*) {
    std::cerr << "Error " << code << " executing: " << cmd << std::endl;
});

// Check return codes for setup errors
if (gcode.Connect(ip) != GCODE_OK) {
    throw std::runtime_error("Connection failed");
}

// WaitForQueueEmpty with timeout handling
int result = gcode.WaitForQueueEmpty(30000);
if (result == GCODE_ERR_TIMEOUT) {
    gcode.Stop();
    gcode.ClearQueue();
    // Handle timeout...
}

Common Error Scenarios

GCODE_ERR_PROCESSING_ACTIVE

This error occurs when calling configuration methods while G-code execution is running. To resolve, stop processing before changing configuration:

gcode.Stop();
gcode.WaitForQueueEmpty();  // Wait for current command to finish
gcode.ConfigureLinearAxis('X', 'A', 2000.0);  // Now safe to configure
gcode.Start();  // Resume processing

GCODE_ERR_PARSE_FAILED

This error indicates the G-code command could not be parsed. Common causes:

Unsupported G-code (check Supported G-Codes)
Syntax error in the command
Missing required parameters

GCODE_ERR_CONNECTION_FAILED

Connection failures typically indicate:

Controller is not powered on
Incorrect IP address
Network connectivity issue