errors

nexutils/errors

^{the errors module, part of GSF-nexutils, member of the tiny-frameworks family}

The errors module provides a structured, lightweight error handling framework for Go applications. It combines domain-specific error codes, contextual tracking paths, full compatibility with standard Go error unwrapping (errors.Is / errors.As), and seamless integration with structured loggers.

Features

• Structured Error Codes: Categorize errors with type-safe, domain-specific error codes.
• Context & Paths: Attach call-site or component path information for easy debugging.
• Go Standard Compatibility: Implements Unwrap() to work seamlessly with errors.Is() and errors.As().
• Exit-Code Mapping: Central registry to map application error codes directly to OS exit codes (ideal for CLI tools and microservices).
• Structured Logging Integration: Built-in helper (LogError) to pass structured key-value context directly to loggers implementing an Error(msg string, args ...any) interface (e.g., slog).

Installation

go get codeberg.org/tiny-frameworks/nexutils/errors

Quick Start

1. Creating and Wrapping Errors

package main

import (
	stdErrors "errors"
	"fmt"

	"codeberg.org/tiny-frameworks/nexutils/errors"
)

func main() {
	// Create a new structured error
	err := errors.New(
		errors.MissingField,
		"mandatory field 'email' is missing",
		"user.service.Validate()",
	)
	fmt.Println(err)
	// Output: [MISSING_FIELD] mandatory field 'email' is missing (Path: user.service.Validate())

	// Wrap an existing underlying error
	cause := stdErrors.New("connection timeout")
	wrappedErr := errors.Wrap(
		errors.ReadError,
		"failed to read configuration from remote",
		"config.loader.Fetch()",
		cause,
	)
	fmt.Println(wrappedErr)
	// Output: [READ_ERROR] failed to read configuration from remote (Path: config.loader.Fetch()): connection timeout
}

Core Concepts

Go Standard Compatibility (Is & As)

The errors module re-exports errors.Is, errors.As, and errors.Unwrap from the Go standard library, ensuring full chain inspection while maintaining a single import footprint:

// Check if a specific root cause exists anywhere in the error chain
if errors.Is(err, stdErrors.ErrNotExist) {
	// Handle missing resource...
}

// Extract a structured *errors.Error from an unknown error chain
var nexErr *errors.Error
if errors.As(err, &nexErr) {
	fmt.Printf("Error Code: %s, Path: %s\n", nexErr.Code, nexErr.Path)
}

Structured Logging with LogError

The LogError utility automatically extracts structured fields (code, path, cause) from an error and forwards them as key-value pairs to any compatible logger (such as log/slog or custom loggers):

type Logger interface {
	Error(msg string, args ...any)
}

// Usage in your application code
errors.LogError(logger, err)
// Automatically logs: msg="failed to read..." code="READ_ERROR" path="config.loader" cause="..."

Exit Code Registry

Errors can be mapped to predefined OS exit codes for consistent process exit behavior across services and CLI utilities:

// Retrieve the numerical exit code associated with a specific Error Code
exitCode := errors.GetExitCode(err)
os.Exit(exitCode)

Exit Code Range Convention

API Reference

Testing

Run unit tests and verify error chain behavior:

go test -v ./...

Organizational & Standards

• Copyright: © 2026 Georg Hagn.
• Namespace: codeberg.org/tiny-frameworks/nexutils/errors
• License: Apache License, Version 2.0.

GSF-nexutils/errors is an independent open-source project and is not affiliated with any corporation of a similar name.

Contact

If you have questions or feedback, feel free to reach out:

📧 georghagn [at] tiny-frameworks.io