OPAL Errors

Error codes and troubleshooting reference

OPAL Errors

Reference for all error types, codes, and resolution strategies in OPAL.

Pro Tip

Error codes in OPAL follow a pattern: E1xx for syntax, E2xx for runtime, E3xx for types, E4xx for resources, E5xx for permissions, E6xx for communication. When you see E207 (timeout), it almost always means your loop is missing a delay(). When you see E501, check your Plan's permission declarations.

Error categories

Category	Code Range	Description
Syntax	E1xx	Parse and syntax errors
Runtime	E2xx	Execution errors
Type	E3xx	Type mismatch errors
Resource	E4xx	Hardware/resource errors
Permission	E5xx	Access denied errors
Communication	E6xx	Network/messaging errors

Syntax errors (E1xx)

E101: Unexpected token

Message: Unexpected token '{token}' at line {line}

Cause: Parser encountered an unexpected character or keyword.

Example:

// Wrong
if distance < 30
    stop()
}

// Correct
if distance < 30 {
    stop()
}

Resolution: Check for missing brackets, parentheses, or operators.

E102: Missing closing bracket

Message: Expected '}' at line {line}, found end of file

Cause: Opening { without matching closing }.

Example:

// Wrong
plan Example {
    loop {
        do_something()
    // Missing }
}

// Correct
plan Example {
    loop {
        do_something()
    }
}

Resolution: Ensure all { have matching }.

E103: Missing closing parenthesis

Message: Expected ')' at line {line}

Cause: Opening ( without matching ).

Example:

// Wrong
if (distance < 30 {
    stop()
}

// Correct
if (distance < 30) {
    stop()
}

E104: Invalid identifier

Message: Invalid identifier '{name}' at line {line}

Cause: Variable or function name contains invalid characters.

Example:

// Wrong - starts with number
var 2speed = 50

// Wrong - contains hyphen
var my-speed = 50

// Correct
var speed2 = 50
var my_speed = 50

Resolution: Use letters, numbers, and underscores. Start with letter.

E105: Missing string terminator

Message: Unterminated string at line {line}

Cause: String literal not closed.

Example:

// Wrong
log("Hello world)

// Correct
log("Hello world")

E106: Invalid number

Message: Invalid number format at line {line}

Cause: Malformed numeric literal.

Example:

// Wrong
var x = 1.2.3
var y = 1e

// Correct
var x = 1.23
var y = 1e10

E107: Reserved word

Message: '{word}' is a reserved keyword at line {line}

Cause: Using a reserved word as identifier.

Reserved words: if, else, for, while, loop, break, continue, return, var, const, function, plan, true, false, null

Runtime errors (E2xx)

E201: Undefined variable

Message: Variable '{name}' is not defined at line {line}

Cause: Referencing a variable that doesn't exist.

Example:

// Wrong
var distance = 50
if distanc < 30 {  // Typo!
    stop()
}

// Correct
if distance < 30 {
    stop()
}

Resolution: Check spelling, ensure variable is declared.

E202: Undefined function

Message: Function '{name}' is not defined at line {line}

Cause: Calling a function that doesn't exist.

Example:

// Wrong
stopMotors()  // Function doesn't exist

// Correct
stop()  // Use built-in function

Resolution: Check function name, ensure it's defined.

E203: Division by zero

Message: Division by zero at line {line}

Cause: Dividing by zero.

Example:

// Wrong
var speed = 100
var time = 0
var rate = speed / time  // Division by zero!

// Correct
if time != 0 {
    var rate = speed / time
}

Resolution: Check denominator before division.

E204: Index out of bounds

Message: Index {index} out of bounds for array of length {length}

Cause: Accessing array element that doesn't exist.

Example:

// Wrong
var arr = [1, 2, 3]
var x = arr[5]  // Only indices 0-2 exist

// Correct
if 5 < length(arr) {
    var x = arr[5]
}

E205: Null reference

Message: Cannot access property of null at line {line}

Cause: Accessing property on null value.

Example:

// Wrong
var data = null
var x = data.value  // data is null!

// Correct
if data != null {
    var x = data.value
}

E206: Stack overflow

Message: Maximum call stack exceeded

Cause: Too many nested function calls (usually recursion).

Example:

// Wrong - infinite recursion
function count(n) {
    return count(n + 1)  // Never stops!
}

// Correct - has base case
function count(n) {
    if n >= 100 {
        return n
    }
    return count(n + 1)
}

E207: Timeout

Message: Execution timeout after {ms}ms

Cause: Plan took too long to execute.

Example:

// Wrong - infinite loop without delay
loop {
    // No delay, uses 100% CPU
}

// Correct
loop {
    do_work()
    delay(50)  // Required delay
}

E208: Out of memory

Message: Memory limit exceeded

Cause: Plan used too much memory.

Example:

// Wrong - grows forever
var history = []
loop {
    push(history, sensors.distance.front)
    // Never clears old data
}

// Correct - limit size
var history = []
loop {
    push(history, sensors.distance.front)
    if length(history) > 1000 {
        shift(history)  // Remove oldest
    }
}

Type errors (E3xx)

E301: Type mismatch

Message: Cannot {operation} {type1} and {type2}

Cause: Incompatible types in operation.

Example:

// Wrong
var x = "hello" + 5  // string + number

// Correct
var x = "hello" + to_string(5)

E302: Invalid comparison

Message: Cannot compare {type1} with {type2}

Cause: Comparing incompatible types.

Example:

// Wrong
var state = "running"
if state < 30 {  // string vs number
    stop()
}

// Correct
if state == "running" {
    stop()
}

E303: Not callable

Message: '{name}' is not a function

Cause: Trying to call a non-function value.

Example:

// Wrong
var speed = 50
speed()  // speed is a number, not function

// Correct
set_motor("left", speed)

E304: Not iterable

Message: '{type}' is not iterable

Cause: Trying to iterate non-iterable value.

Example:

// Wrong
var count = 10
for x in count {  // numbers aren't iterable
    log(x)
}

// Correct
for x in 0..count {
    log(x)
}

E305: Invalid property access

Message: Cannot access property '{name}' on {type}

Cause: Accessing property on wrong type.

Example:

// Wrong
var x = 42
var y = x.length  // numbers don't have length

// Correct
var s = "hello"
var y = length(s)  // Use function instead

Resource errors (E4xx)

E401: Sensor not found

Message: Sensor '{name}' not found

Cause: Referencing a sensor that doesn't exist.

Example:

// Wrong
var temp = sensors.temperature.rear  // No rear temp sensor

// List available sensors
log(sensors.list())

Resolution: Check sensor configuration, verify sensor name.

E402: Actuator not found

Message: Actuator '{name}' not found

Cause: Referencing a motor/servo that doesn't exist.

Example:

// Wrong
set_motor("arm", 50)  // No "arm" motor configured

Resolution: Check hardware configuration.

E403: Hardware disconnected

Message: Hardware controller not connected

Cause: Arduino or controller disconnected.

Resolution:

Check USB connection
Verify controller power
Restart hardware connection

E404: Sensor read error

Message: Failed to read sensor '{name}'

Cause: Sensor returned invalid data.

Resolution:

Check sensor wiring
Verify sensor power
Test sensor independently

E405: Actuator write error

Message: Failed to write to actuator '{name}'

Cause: Could not send command to actuator.

Resolution:

Check actuator wiring
Verify power supply
Check for mechanical issues

E406: Resource busy

Message: Resource '{name}' is in use

Cause: Resource locked by another plan.

Resolution: Wait for resource or coordinate access.

Permission errors (E5xx)

E501: Permission denied

Message: Permission denied: {action}

Cause: Plan lacks required permission.

Example:

// Error if plan doesn't have "control.motors" permission
drive(50, 50)

Resolution: Add required permission to plan configuration.

E502: Trust level insufficient

Message: Action requires trust level {required}, have {current}

Cause: Peer trust level too low for action.

Resolution: Increase trust level in pairing configuration.

E503: Actuator disabled

Message: Actuator '{name}' is disabled

Cause: Actuator explicitly disabled for safety.

Resolution: Enable actuator in settings if safe.

E504: Read-only access

Message: Cannot write to '{name}': read-only

Cause: Trying to modify read-only value.

Example:

// Wrong
sensors.distance.front = 50  // Sensors are read-only

Communication errors (E6xx)

E601: Peer not found

Message: Peer '{name}' not found

Cause: Sending to unknown peer.

Example:

// Wrong - peer doesn't exist
send_to("Unknown Robot", "message", {})

Resolution: Verify peer is paired and online.

E602: Message timeout

Message: Message to '{peer}' timed out

Cause: Peer didn't respond in time.

Resolution: Check network connection, peer status.

E603: Network error

Message: Network error: {details}

Cause: Network communication failure.

Resolution: Check network connectivity, firewall settings.

E604: Invalid message

Message: Invalid message format

Cause: Received malformed message.

Resolution: Check message data format.

Error handling

Using try/catch

try {
    var dist = sensors.distance.front
    if dist < 30 {
        stop()
    }
} catch error {
    log_error("Sensor error: " + error.message)
    // Fallback behavior
    stop()
}

Error object properties

catch error {
    error.code      // e.g., "E401"
    error.message   // Human-readable message
    error.line      // Line number where error occurred
    error.stack     // Call stack trace
}

Conditional error handling

try {
    risky_operation()
} catch error {
    if error.code == "E401" {
        // Handle missing sensor
        use_fallback_sensor()
    } else if error.code == "E403" {
        // Handle disconnection
        wait_for_reconnection()
    } else {
        // Unknown error - stop safely
        stop()
        throw error  // Re-throw
    }
}

Debugging tips

Enable verbose logging

log_debug("Variable state: " + to_string(my_var))

Check variable types

log("Type of x: " + typeof(x))

Use breakpoints

Set breakpoints in the Plan Editor to pause execution.

Monitor sensors

Use Sensor Monitor to verify readings before using in code.