FreeBasic Error Handling: On Error, Error and Err

Last modified October 18, 2026

FreeBASIC has no Try, Catch, or Throw keywords. Runtime errors are handled with the On Error Goto statement, the Error statement, and the Err function.

Basic Definition

On Error Goto label sets the error handler: when an error occurs, execution jumps to label. Error n raises the error number n. Err returns the number of the current error inside the handler. If no handler is set, Error aborts the program with a runtime error message.

Error handling separates error recovery from normal program flow. The handler is kept in one place, so the main code stays readable.

Simple Error Handler Example

This basic example demonstrates the fundamental structure of error handling.

simple_error_handler.bas

Dim Shared code As Integer

On Error Goto handler
Print "Inside main block"
Error 5
Print "This won't execute"
End
handler:
code = Err
Print "Caught error number: "; code
End

The program raises error 5 with Error 5. The jump to handler happens, and the second Print statement never executes. The output is:

Inside main block
Caught error number:  5

Note that Err is read into a variable first. The handler's End stops the program, so control does not return to the main code.

Distinguishing Error Numbers

FreeBASIC has no typed exceptions. A single handler receives an error number, and Select Case on Err distinguishes the cases.

multiple_errors.bas

Dim Shared code As Integer
Dim choice As Integer

On Error Goto handler
choice = 2
Select Case choice
    Case 1: Error 5
    Case 2: Error 11
    Case 3: Error 7
End Select
End
handler:
code = Err
Select Case code
    Case 5: Print "Illegal function call"
    Case 11: Print "Division by zero"
    Case 7: Print "Out of memory"
    Case Else: Print "Other error: "; code
End Select
End

The Error statement raises the chosen number, and the handler selects the message with Select Case. The output is:

Division by zero

Error Propagation from Functions

Errors raised in a function or sub without a local handler are passed to the handler set by the calling code. The Divide function below raises error 11 for division by zero.

function_error.bas

Dim Shared code As Integer

Function Divide(a As Integer, b As Integer) As Double
    If b = 0 Then Error 11
    Return a / b
End Function

On Error Goto handler
Print Divide(10, 2)
Print Divide(5, 0)
Print "This won't execute"
End
handler:
code = Err
Print "Error number: "; code
End

The first call returns 5. The second call raises error 11, and the program jumps to handler. The output is:

 5
Error number:  11

Custom Error Numbers

The Error statement accepts any number, so custom error numbers can be used to identify application-specific failures. Built-in runtime error numbers are listed in the FreeBASIC wiki, and custom numbers do not clash with them as long as they are used consistently.

custom_error.bas

Dim Shared code As Integer

On Error Goto handler
Error 1001
Print "This won't execute"
End
handler:
code = Err
Print "Custom error code: "; code
End

The output is:

Custom error code:  1001

Cleanup Without Finally

FreeBASIC has no Finally block. Cleanup code is placed in the error handler, as shown in the next example.

handler_cleanup.bas

Dim Shared fnum As Integer
Dim Shared code As Integer

On Error Goto handler
fnum = FreeFile
Open "test.txt" For Output As #fnum
Print #fnum, "some data"
Error 9
Print "This won't execute"
End
handler:
code = Err
Print "Error: "; code
Close #fnum
Print "File closed in handler"
Kill "test.txt"
End

The handler closes the file before the program ends, so the file is closed after an error. The output is:

Error:  9
File closed in handler

Rethrowing Errors

A procedure without a local handler passes its error to the caller's handler. This is the closest equivalent to rethrowing: the error is not handled in the procedure and reaches the outer handler.

rethrow_error.bas

Dim Shared code As Integer

Sub ProcessData()
    Print "Processing data"
    Error 7
    Print "not reached"
End Sub

On Error Goto mainhandler
ProcessData()
Print "not reached"
End
mainhandler:
code = Err
Print "Caught error from ProcessData: "; code
End

The Sub has no local handler, so error 7 passes to mainhandler. The output is:

Processing data
Caught error from ProcessData:  7

Best Practices

Specific error numbers: Use distinct error numbers and test Err with Select Case.
Meaningful messages: Print or log a descriptive message for each error number.
Resource cleanup: Close files and free resources in the error handler.
Do not ignore: Avoid empty handlers that swallow errors.
Documentation: Document which error numbers functions can raise.

This tutorial covered FreeBASIC error handling with On Error Goto, Error, and Err, with practical examples in different 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 FreeBasic Tutorials.

Ebooks