All notable changes to this project are documented here. The format follows
Keep a Changelog; this project adheres
to Semantic Versioning. Pre-v1.0.0
the public API may change between minor versions.
Errortype with stable identity (domain+code),Class(expected/defect/cancelled),Severity, separate operator and end-user message,Hint,Owner, retry metadata.- Constructors:
New,Newf,Wrap,Wrapf,Note(note-without-rewrap),Join. - Transparent wrapping with inner-identity inheritance; explicit
Opaque()barrier. - Standard-library interop:
Unwrap() []error(cause + suppressed), works witherrors.Is/errors.As/errors.Join. - Generic
As[T], plusGet,Code,HasCode,FindByCode,ClassOf,IsExpected/IsDefect/IsCancelled,IsRetryable,RetryAfter. - Typed structured fields with per-field
Safeflag; redaction enforced atSnapshot. - Lazy single-
runtime.Callersstack capture;Frames()symbolizes on demand. - Suppressed (secondary) errors, kept matchable via
errors.Is. - Two-mode accumulation:
Accumulator,Accumulate,ParAccumulate(goroutine-safe) with per-field paths. - Deterministic, message-independent
Fingerprint(FNV-1a of domain+code+origin frame). - Neutral
ReportDTO +Snapshot+Sinkinterface + explicitRegistry(noinit()magic) — the single adapter seam. fmt.Formatter(%s/%q/%+v) andslog.LogValuer.Recover/RecoverDo/Recovered: panic → structured *Error (ClassDefect, SevFatal), original error preserved as cause.RegisterContextExtractor+Error.Context(ctx): pluggable context→error enrichment (trace/span ids, request fields) with explicit registration, noinit().errtestsubpackage:Code/Class/Retryable/InChain/HasCode/NoError/Fingerprintassertion helpers.- Apache-2.0 license,
Taskfile.yml,.golangci.yml, GitHub Actions CI (core + per-contrib-module),go.workfor local multi-module dev.
contrib/httpx(stdlib-only): RFC 9457application/problem+json—Problem,FromError,StatusFor(code + class → HTTP status),Write,RegisterStatus/RegisterType. Unsafe fields never leak (consumes the redactedReport).contrib/otel: OpenTelemetrySinkrecording the error as anexceptionspan event with exception.* semconv + span status Error;Install()registers a context extractor for trace/span ids.contrib/sentry:Sinkcapturing events with level from severity, code/domain tags, the core fingerprint as the Sentry grouping key, safe fields as context,mechanism.handled=true, oldest-first stack.contrib/prometheus:Sinkincrementingerrx_errors_total{code,domain,severity,class}— labels from stable identity (bounded cardinality; variable messages don't split the series).contrib/grpc:Status/Err/CodeFor— code+class → canonical gRPC code, withErrorInfo(stable reason/domain + safe metadata),RetryInfo,LocalizedMessage,Helptyped details.codec(core, stdlib-only):Encode/Decode+json.Marshaler— cross-service wire round-trip preserving identity/class/severity/retry/ fingerprint soCode/HasCode/IsRetryable/ClassOfkeep working after the hop; unsafe fields never serialized.SampledSink(core): per-fingerprint rate limiting (PerFingerprint) so one hot error can't blow the Sentry bill; surfaces aerrx.sampled_droppedcount on the next allowed report instead of silently dropping.contrib/connect: ConnectRPCError/CodeFor— code+class → Connect code withErrorInfotyped detail (safe metadata only).contrib/graphql: gqlgenPresentErrorPresenter — public message → Message, identity + safe fields → Extensions (extensions.code), internal detail never exposed.contrib/goerr: migration shim —From(goerr → errx, chain-aware) andTo(errx → goerr) for incremental adoption; unsafe fields never cross the bridge.OnError/OnSuccess(Zigerrdefersemantics) +CloseSuppressing/AppendSuppressed: fix the classicdefer f.Close()masking bug — a failing Close is attached as a secondary error, never masking the primary.resultsubpackage (optional, generics):Result[T]withOk/Err/From/Try,Map/AndThen/MapErr/Recover/Match/Collect,Unwrap/UnwrapOr. Never required — idiomatic(value, error)stays the primary interface.- Diagnostic layer (miette-style):
WithURL/WithSource/WithLabelon the core error, plus a stdlib-onlydiagsubpackage with a graphical report handler (severity+code header,-->source pointer, source line with caret^^^underline + label, help, docs URL) and a narratable handler (prose, for CI / pipes / screen readers);diag.Auto()selects based onNO_COLOR/CI/TTY. Nothing in Go shipped this before. - i18n:
WithLocalized(locale, msg)/Localized(locale, fallback)with BCP-47 language fallback (fr-CA → fr-FR). Carried intoReport, gRPCLocalizedMessage(one per locale), RFC 9457localized, and GraphQLextensions.localized. - Error documentation registry:
RegisterDoc(code, DocEntry{URL, Summary, Remediation});URL()/Remediation()resolve from the registry when not set explicitly (explicit always wins). Flows intoReport.DocURL, gRPCHelp, RFC 9457docUrl, GraphQLextensions.docUrl, and thediagreport. - Return-trace:
Error.Trace()andReport.Trace— one frame per wrap layer (innermost-first), the path the error traveled, distinct from the origin stack; shown in%+v. Cheap (one PC perWrap), goroutine-safe. codec:RegisterCodeMigration(old, new)—Decoderewrites retired codes (chain + cycle guard) for cross-version-skew tolerance.- Behavioral code detection:
Code/HasCodenow also honor any error exposingCode() string, so foreign /errxgen-generated typed errors are first-class without being*errx.Error. cmd/errxgen: AST-based generator (thiserror parity — Go has no derive macros). A//errxgen: message=... args=... code=... unwrap=...directive emitsError()/Code()/Unwrap(); generated code imports onlyfmt. Ships a runnable, CI-tested example; CI fails if generated code is stale.- Runnable
Example_*(pkg.go.dev docs + tests). - Core test coverage ~94%;
errtest/result100%; everycontribmodule ≥90% (httpx/connect/graphql/prometheus100%,goerr98%,otel94%,grpc92%,sentry91%). contrib/otelnow requires Go 1.25+ (tracks OpenTelemetry v1.43+); its CI matrix uses Go 1.25. All other modules remain Go 1.24.- Per-contrib-module GitHub Actions CI (8 modules);
go.workis local-dev only (git-ignored) so each module builds standalone (ecosystem rule #5).