Errors

Overview

gogenfilter uses branded errors with [gogenfilter:<code>] prefixes for structured error handling. Every error carries a machine-readable ErrorCode and a descriptive message. Use errors.Is for sentinel matching and .ErrorCode() for programmatic access.

Error Types

ProjectRootError

Returned when the project root cannot be found or resolved.

type ProjectRootError struct {
    Code      ErrorCode
    StartPath string
    Markers   []string
    Err       error
}

When it occurs: FindProjectRoot fails to locate a go.mod or other marker file, or cannot resolve the start path.

FilterConfigError

Returned when a filter configuration option is invalid.

type FilterConfigError struct {
    Code   ErrorCode
    Option FilterOption
    Err    error
}

When it occurs: WithFilterOptions receives an unrecognized FilterOption value.

SQLCConfigError

Returned when a sqlc configuration file cannot be found, read, parsed, or collected.

type SQLCConfigError struct {
    Code       ErrorCode
    ConfigPath string
    Operation  string
    Message    string
    Err        error
}

When it occurs: FindSQLCConfigs, GetSQLOutputDirs, or internal sqlc parsing fails.

FindProjectRoot

Locates the project root by searching upward for marker files.

FindProjectRoot(startPath string, markers []string) (string, *ProjectRootError)

Searches from startPath upward (up to 10 levels) for any of the markers files. If no marker is found, returns ErrProjectRootNotFound. If the start path is invalid, returns ErrProjectRootInvalidPath.

root, err := gogenfilter.FindProjectRoot(
    "./internal/pkg",
    []string{"go.mod", "go.sum"},
)
if err != nil {
    // handle error
}

Error Codes

ErrorCode is a string type for machine-readable error classification:

type ErrorCode string

All error codes are defined as ErrorCode constants:

Constant	Code
CodeProjectRootNotFound	project_root_not_found
CodeProjectRootInvalidPath	project_root_invalid_path
CodeInvalidFilterOption	invalid_filter_option
CodeSQLCConfigRead	sqlc_config_read
CodeSQLCConfigParse	sqlc_config_parse
CodeSQLCConfigWalk	sqlc_config_walk
CodeSQLCConfigCollect	sqlc_config_collect
CodeSQLCConfigFind	sqlc_config_find

Sentinel Errors

Sentinel errors have zero-value domain fields — matching is by ErrorCode only. Use errors.Is for comparison.

Sentinel	Error Type	Code
ErrProjectRootNotFound	*ProjectRootError	project_root_not_found
ErrProjectRootInvalidPath	*ProjectRootError	project_root_invalid_path
ErrInvalidFilterOption	*FilterConfigError	invalid_filter_option
ErrSQLCConfigRead	*SQLCConfigError	sqlc_config_read
ErrSQLCConfigParse	*SQLCConfigError	sqlc_config_parse
ErrSQLCConfigWalk	*SQLCConfigError	sqlc_config_walk
ErrSQLCConfigCollect	*SQLCConfigError	sqlc_config_collect
ErrSQLCConfigFind	*SQLCConfigError	sqlc_config_find

Interfaces

All error types implement the ErrorCoder interface:

type ErrorCoder interface {
    ErrorCode() ErrorCode
}

Error Matching

errors.Is — Sentinel Matching

_, err := gogenfilter.FindProjectRoot(
    "/nonexistent",
    []string{"go.mod"},
)
if errors.Is(err, gogenfilter.ErrProjectRootNotFound) {
    // handle project root not found
}

errors.AsType — Type Extraction (Go 1.26+)

Extracts a branded error from a generic error variable:

var err error = maybeReturnProjectRootError()
projErr, ok := errors.AsType[*gogenfilter.ProjectRootError](err)
if ok {
    fmt.Println(projErr.ErrorCode())
    fmt.Println(projErr.StartPath)
}

Unwrap() — Error Chains

All error types implement Unwrap() for error chain traversal with errors.Is and errors.As. The inner error is accessible via the Err field.

Error Message Format

All errors produce branded messages with the [gogenfilter:<code>] prefix:

[gogenfilter:project_root_not_found] project root not found from "/some/path" (searched for: go.mod)
[gogenfilter:sqlc_config_read] sqlc config read "sqlc.yaml": reading sqlc config: permission denied

This format enables easy grep and log filtering.