Error Handling and Logging

Relevant source files

Purpose: This page documents Basalt2's error handling and logging systems, which provide comprehensive error reporting with stack traces, source code context, and configurable logging capabilities for debugging and monitoring.

Scope: Covers the errorManager module for error handling and display, the log module for structured logging, and integration patterns throughout the runtime. For information about the build pipeline and development tools, see Build Pipeline.

System Overview

Basalt2 implements a two-tier system for error management and logging:

Diagram: Error Handling and Logging Architecture

Sources: src/main.lua1-604 config.lua17-24 config.lua33-40 release/basalt.lua53-83

The Error Manager

The errorManager module provides formatted error display with stack traces, source code context, and terminal output formatting.

Module Structure

Property	Type	Default	Description
`tracebackEnabled`	`boolean`	`true`	Whether to display full stack traces
`header`	`string`	`"Basalt Error"`	Contextual error header (dynamically set)
`errorHandled`	`boolean`	`false`	Flag to prevent recursive error handling

Method	Parameters	Description
`error(message)`	`string`	Formats and displays error, then propagates

Sources: release/basalt.lua53-83

Error Display Process

When errorManager.error(message) is called, the following sequence occurs:

Diagram: Error Display Flow

Sources: release/basalt.lua56-83

Color-Coded Output

The error manager uses terminal colors to improve readability:

Element	Color	Purpose
Error header	`colors.red`	Immediate visual identification
Stack trace lines	`colors.gray`	Secondary information
File paths	`colors.lightGray`	File identification
Line numbers	`colors.lightBlue`	Quick line reference
Error message	`colors.red`	Primary error description
Source line indicator	`colors.cyan`	Context highlight
Source code	`colors.lightGray`	Code display

Sources: release/basalt.lua54-83

The Logging System

The log module provides structured logging with multiple severity levels and optional file output.

Log Module API

Diagram: Logging API Structure

Sources: BasaltLS.lua251-270 config.lua33-40

Usage Patterns

The logging system is accessed through basalt.LOGGER:

Sources: src/main.lua27 src/main.lua465 src/main.lua497 src/main.lua526 src/main.lua556

Runtime Error Handling

The Basalt runtime implements comprehensive error handling at multiple levels to ensure robust operation and clear error reporting.

Error Handling Points in main.lua

Diagram: Runtime Error Catching Architecture

Sources: src/main.lua183-195 src/main.lua248-299 src/main.lua311-323 src/main.lua336-359 src/main.lua424-431

Error Context Types

Basalt sets contextual error headers based on where the error originated:

Context	Header	Location	Purpose
Runtime loop	`"Basalt Runtime Error"`	src/main.lua319 src/main.lua355	Main event loop failures
Scheduled functions	`"Basalt Schedule Error"`	src/main.lua191 src/main.lua283	`basalt.schedule()` coroutine errors
Event processing	`"Basalt Event Error"`	src/main.lua254 src/main.lua268	Event dispatch failures
Event callbacks	`"Basalt Event Callback Error"`	src/main.lua427	User callback errors
Loading errors	`"Basalt Loading Error"`	release/basalt.lua200	Initialization failures
Program errors	`"Basalt Program Error"`	release/basalt.lua304 release/basalt.lua307-309	Program element errors

Sources: src/main.lua183-431

Schedule Error Handling Example

When a scheduled function throws an error:

Sources: src/main.lua178-195

Event Queue Error Handling

The event queue system catches errors in coroutines:

Sources: src/main.lua248-263

Integration Patterns

Error Handling in basalt.run()

The main runtime loop uses nested pcall to ensure the application continues running even after errors:

Diagram: Runtime Error Recovery

Sources: src/main.lua336-359

Error Handling in Event Callbacks

Event callbacks receive special error handling that doesn't crash the application:

Sources: src/main.lua421-432

Configuration and Best Practices

Disabling Stack Traces

For production environments, stack traces can be disabled:

This reduces visual clutter but still provides error messages and source context.

Sources: release/basalt.lua54

Logging Configuration

The log module can be configured at runtime:

Sources: BasaltLS.lua263-270

Custom Error Headers

When catching errors in custom code, set contextual headers:

Sources: src/main.lua191 src/main.lua254 src/main.lua283 src/main.lua319 src/main.lua355 src/main.lua427

Logging Levels in Practice

Use appropriate log levels for different scenarios:

Level	Use Case	Example
`debug()`	Development information	Configuration applied, internal state changes
`info()`	Normal operation milestones	Element loaded, manifest processed
`warn()`	Recoverable issues	Failed to load optional element, deprecated API used
`error()`	Error conditions	Required element missing, invalid configuration

Sources: src/main.lua465 src/main.lua497 src/main.lua526 src/main.lua556

Error Manager Reference

Properties

tracebackEnabled: boolean - Controls stack trace display (default: true)
header: string - Error context header, dynamically set by runtime (default: "Basalt Error")
errorHandled: boolean - Internal flag to prevent recursive error handling (default: false)

Methods

error(message): Formats and displays an error with stack trace, source context, and colored terminal output. Calls log.error() and then propagates the error.