Tcl error Command

last modified October 20, 2026

The Tcl error command is used to generate errors and exceptions. It allows scripts to signal error conditions with custom messages. Proper error handling makes scripts more robust and maintainable.

Basic Definition

The error command raises an error with a specified message. It terminates script execution unless caught by a catch (or try) command. The optional arguments set the initial stack trace (info) and the machine-readable error code (code).

Syntax: error message ?info? ?code?. The message is required while info and code are optional. The info provides stack trace details.

Basic Error Generation

This example shows the simplest usage of error to raise an error.

basic_error.tcl

error "This is a basic error message"

When executed, this script will terminate and display the error message. No further commands will execute after the error is raised.

Catching Errors

The catch command can trap errors raised by error.

catch_error.tcl

if {[catch {error "Division by zero"} msg]} {
    puts "Caught error: $msg"
}

Here we use catch to prevent script termination. The error message is stored in msg and printed instead of terminating execution.

Error with Stack Trace

The optional info parameter can provide stack trace information for debugging.

error_stack.tcl

proc divide {a b} {
    if {$b == 0} {
        error "Division by zero" "Attempted division of $a by $b"
    }
    return [expr {$a / $b}]
}

catch {divide 10 0} msg opts
puts $msg
puts [dict get $opts -errorinfo]

This shows a division function that raises an error with stack info. The catch captures both the message and the options dictionary. The text passed as info replaces the beginning of the trace in -errorinfo, and Tcl appends the frames the error passed through ("procedure "divide"" and "invoked from within"). The message itself is not repeated there.

Custom Error Codes

Error codes help categorize errors programmatically for better handling.

error_code.tcl

proc validate_age {age} {
    if {$age < 0} {
        error "Invalid age" "" NEGATIVE_AGE
    } elseif {$age > 120} {
        error "Invalid age" "" TOO_OLD
    }
    return $age
}

catch {validate_age -5} msg opts
puts "Error code: [dict get $opts -errorcode]"

This validation function uses custom error codes. The calling code can check the error code to determine the specific validation failure. By convention an error code is a list whose first element names the area, such as {MYAPP NEGATIVE_AGE}, which can be matched with try ... trap.

Nested Error Handling

Errors can be caught and re-raised with additional context when needed.

nested_error.tcl

proc process_data {data} {
    if {$data eq ""} {
        error "Empty data received"
    }
    # Process data here
}

proc main {} {
    set input ""
    if {[catch {process_data $input} msg]} {
        error "Processing failed: $msg" $::errorInfo
    }
}

catch {main} msg
puts $msg

This shows nested error handling where a low-level error is caught and re-raised with additional context. The stack trace of the original error is passed as the info argument, so it is kept at the start of the new trace. $::errorInfo holds the trace of the most recent error; the options dictionary captured by catch is a more reliable source. The new error has its own error code, so the original one is lost unless it is passed on too.

Error in Procedures

Procedures can use error to validate inputs and report problems.

proc_error.tcl

proc calculate_area {width height} {
    if {$width <= 0 || $height <= 0} {
        error "Dimensions must be positive"
    }
    return [expr {$width * $height}]
}

if {[catch {calculate_area 0 10} msg]} {
    puts "Calculation error: $msg"
} else {
    puts "Area: $msg"
}

This procedure validates its inputs before calculation. Invalid dimensions trigger an error that can be caught by the calling code.

Best Practices

Messages: Provide clear, descriptive error messages.
Catch: Catch errors at the level where you can recover; try ... trap matches on the error code.
Codes: Use error codes for programmatic handling.
Info: Include stack info for debugging complex errors.
Validation: Validate inputs early and fail fast.

This tutorial covered the Tcl error command with practical examples showing its usage in different error handling scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Tcl Tutorials.

Ebooks