CockroachDB Errors Migration Specification¶

Authors

Matt Cockayne, Claude (claude-4.6-opus) (AI drafting assistant)

Date

18 February 2026

Status

IMPLEMENTED

1. Overview¶

1.1 Motivation¶

GTB currently uses github.com/go-errors/errors (v1.5.1) for error creation and wrapping. While this library provides stack traces, it lacks several capabilities that would significantly improve the developer and user experience:

• No user-facing hints or details: When errors occur, users see raw error messages with no guidance on how to resolve the issue. The current workaround is embedding multi-line suggestion text directly into error messages via errors.Errorf or errors.WrapPrefix, mixing user-facing content with programmatic error identity.
• No structured error metadata: There is no way to attach machine-readable context (telemetry keys, issue tracker links, safe details) to errors without modifying the error message string.
• Awkward stack trace access: Extracting stack traces requires a type assertion to *errors.Error followed by calling .ErrorStack(). The cockroachdb/errors library supports standard %+v formatting for verbose error output including stack traces.
• No multi-error support: Concurrent operations that can produce multiple errors have no first-class way to combine them.
• No errors.Is/errors.As on the error library itself: The go-errors library's errors.Is and errors.As are wrappers, but cockroachdb/errors provides these as first-class citizens that work correctly through all wrapper layers, including across the network.
• No assertion failure markers: There is no way to distinguish programming errors (invariant violations) from operational errors (expected failure modes).
• Limited wrapping API: WrapPrefix(err, "msg", 0) requires a skip parameter that is almost always 0; cockroachdb/errors provides the cleaner Wrap(err, "msg").

1.2 Proposed Solution¶

Replace github.com/go-errors/errors with github.com/cockroachdb/errors throughout the codebase. This is a like-for-like replacement for basic functionality (error creation, wrapping, stack traces, Is/As) while unlocking a rich set of additional capabilities:

1.3 Terminology¶

1.4 Design Decisions¶

D1: Direct replacement, not abstraction layer. We will import github.com/cockroachdb/errors directly rather than creating an internal wrapper. The cockroachdb/errors package is designed as a drop-in replacement and its API is stable. An abstraction layer would add complexity without benefit.

D2: Retain the ErrorHandler interface. The ErrorHandler interface (Check, Fatal, Error, Warn, SetUsage) remains the primary mechanism for error reporting in commands. The StandardErrorHandler implementation will be enhanced to leverage hints, details, and improved stack trace formatting from cockroachdb/errors.

D3: Preserve sentinel error identity. All existing sentinel errors (ErrNotImplemented, ErrRunSubCommand, ErrNoFilesFound, ErrCommandProtected, etc.) will be migrated to cockroachdb/errors equivalents. Since both libraries define errors.New() that returns types compatible with errors.Is(), identity comparisons will continue to work.

D4: Enhance ErrNotImplemented with UnimplementedError. The cockroachdb/errors library provides UnimplementedError(issueLink, msg) which is purpose-built for this use case and supports issue tracker links. We will migrate ErrNotImplemented to use this.

D5: Use WithHint for user-facing recovery suggestions. Error messages that currently embed multi-line suggestion text (e.g. "failed to connect\n\nSuggestions:\n - Check X\n - Try Y") will be refactored to use errors.WithHint(), separating the error identity from the user guidance.

D6: Stack traces via %+v formatting. The StandardErrorHandler will use fmt.Sprintf("%+v", err) for verbose error output in debug mode instead of the current type-assertion-based .ErrorStack() approach. This is cleaner and works with any error in the cockroachdb/errors chain.

D7: Remove go-errors dependency entirely. After migration, github.com/go-errors/errors will be removed from go.mod. No dual-dependency period.

2. Public API¶

2.1 ErrorHandler Interface (unchanged)¶

The ErrorHandler interface signature remains unchanged to preserve backwards compatibility for all downstream consumers:

type ErrorHandler interface {
    Check(err error, prefix string, level string, cmd ...*cobra.Command)
    Fatal(err error, prefixes ...string)
    Error(err error, prefixes ...string)
    Warn(err error, prefixes ...string)
    SetUsage(usage func() error)
}

2.2 StandardErrorHandler (enhanced)¶

The StandardErrorHandler struct remains structurally the same:

type StandardErrorHandler struct {
    Logger *log.Logger
    Help   HelpConfig
    Exit   ExitFunc
    Writer io.Writer
    Usage  func() error
}

Internal behavioural changes:

1. Stack trace extraction switches from errors.As(err, &es); es.ErrorStack() to fmt.Sprintf("%+v", err) when debug logging is enabled.
2. Hint extraction: When an error carries hints (via errors.WithHint), the handler will extract and display them below the error message using errors.FlattenHints().
3. Detail extraction: When an error carries details (via errors.WithDetail), and the logger is at debug level, the handler will extract and display them using errors.FlattenDetails().
4. Unimplemented detection: ErrNotImplemented detection will use errors.HasUnimplementedError() alongside errors.Is() for broader compatibility.
5. Assertion failure detection: New logic to detect assertion failures via errors.HasAssertionFailure() and log them with elevated severity and a distinct prefix.

2.3 New Constructor¶

func New(logger *log.Logger, help HelpConfig, opts ...Option) ErrorHandler

A functional options pattern is introduced to allow future extensibility without breaking the constructor signature:

type Option func(*StandardErrorHandler)

func WithExitFunc(exit ExitFunc) Option
func WithWriter(w io.Writer) Option

The existing New(logger, help) two-argument constructor will be preserved as a convenience that delegates to the options-based constructor with no options. This maintains full backwards compatibility.

2.4 Sentinel Errors (migrated)¶

Existing sentinels migrate to cockroachdb/errors equivalents:

import "github.com/cockroachdb/errors"

var (
    ErrRunSubCommand = errors.New("subcommand required")
)

ErrNotImplemented is replaced with a function that returns a richer error:

func NewErrNotImplemented(issueURL string) error {
    return errors.UnimplementedError(
        errors.IssueLink{IssueURL: issueURL},
        "command not yet implemented",
    )
}

// ErrNotImplemented is retained as a simple sentinel for backwards compatibility
// with existing errors.Is(err, ErrNotImplemented) checks in downstream consumers.
var ErrNotImplemented = errors.New("command not yet implemented")

Downstream consumers that use errors.Is(err, ErrNotImplemented) will continue to work. The NewErrNotImplemented function is offered for callers that want to attach an issue link.

2.5 New Error Construction Helpers¶

The errorhandling package will export convenience functions that standardise common error patterns across the codebase:

// WithUserHint attaches a user-facing recovery suggestion to an error.
func WithUserHint(err error, hint string) error {
    return errors.WithHint(err, hint)
}

// WithUserHintf attaches a formatted user-facing recovery suggestion.
func WithUserHintf(err error, format string, args ...interface{}) error {
    return errors.WithHintf(err, format, args...)
}

// WrapWithHint wraps an error with a message and attaches a user-facing hint.
func WrapWithHint(err error, msg string, hint string) error {
    return errors.WithHint(errors.Wrap(err, msg), hint)
}

// NewAssertionFailure creates an error denoting a programming bug.
func NewAssertionFailure(format string, args ...interface{}) error {
    return errors.AssertionFailedf(format, args...)
}

These are thin wrappers that exist primarily for discoverability and to establish project conventions. Direct use of cockroachdb/errors functions is also acceptable.

2.6 Exported Constants (updated)¶

const (
    LevelFatal    = "fatal"
    LevelError    = "error"
    LevelWarn     = "warn"
    KeyStacktrace = "stacktrace"
    KeyHelp       = "help"
    KeyHints      = "hints"
    KeyDetails    = "details"
)

Two new log keys (KeyHints, KeyDetails) are added for structured log output.

3. Internal Implementation¶

3.1 Stack Trace Extraction¶

Current implementation (handling.go, Check method):

var es *errors.Error
if errors.As(err, &es) {
    stacktrace = es.ErrorStack()
}

New implementation:

if h.Logger.GetLevel() == log.DebugLevel {
    stacktrace = fmt.Sprintf("%+v", err)
}

The %+v format on cockroachdb/errors produces a structured output containing: - The full error message chain - Stack traces for every wrapper that captured one - Hints, details, safe details, assertion markers, issue links

This is richer than the previous .ErrorStack() output and requires no type assertion.

3.2 Hint and Detail Display¶

When the StandardErrorHandler processes an error, it will check for attached hints and details:

func (h *StandardErrorHandler) logError(err error, prefix, level string) {
    l := h.Logger
    if len(prefix) > 0 {
        l = l.WithPrefix(prefix)
    }

    kvPairs := []any{}

    // Stack trace in debug mode
    if h.Logger.GetLevel() == log.DebugLevel {
        kvPairs = append(kvPairs, KeyStacktrace, fmt.Sprintf("%+v", err))
    }

    // User-facing hints (always displayed when present)
    if hints := errors.FlattenHints(err); hints != "" {
        kvPairs = append(kvPairs, KeyHints, hints)
    }

    // Developer-facing details (debug mode only)
    if h.Logger.GetLevel() == log.DebugLevel {
        if details := errors.FlattenDetails(err); details != "" {
            kvPairs = append(kvPairs, KeyDetails, details)
        }
    }

    // Help/support information
    if h.Help.Slack.Channel != "" && h.Help.Slack.Team != "" {
        kvPairs = append(kvPairs, KeyHelp,
            fmt.Sprintf(SupportMessageFormat, h.Help.Slack.Team, h.Help.Slack.Channel))
    }

    switch level {
    case LevelFatal:
        l.Error(err, kvPairs...)
        h.Exit(1)
    case LevelError:
        l.Error(err, kvPairs...)
    case LevelWarn:
        l.Warn(err, kvPairs...)
    }
}

3.3 Special Error Handling¶

The handleSpecialErrors method will be updated to leverage cockroachdb/errors introspection:

func (h *StandardErrorHandler) handleSpecialErrors(err error, cmd ...*cobra.Command) bool {
    // Unimplemented errors (covers both sentinel and UnimplementedError)
    if errors.Is(err, ErrNotImplemented) || errors.HasUnimplementedError(err) {
        h.Logger.Warn("Command not yet implemented")
        if links := errors.GetAllIssueLinks(err); len(links) > 0 {
            h.Logger.Info("Track progress", "url", links[0].IssueURL)
        }
        return true
    }

    // Subcommand required
    if errors.Is(err, ErrRunSubCommand) {
        if len(cmd) > 0 && cmd[0] != nil {
            cmd[0].SetOut(h.Writer)
            _ = cmd[0].Usage()
        } else if h.Usage != nil {
            _ = h.Usage()
        }
        h.Logger.Warn("Subcommand required")
        return true
    }

    // Assertion failures: log with elevated visibility
    if errors.HasAssertionFailure(err) {
        h.Logger.Error("Internal error (assertion failure)", "error", err)
        if h.Logger.GetLevel() == log.DebugLevel {
            h.Logger.Debug("Assertion detail", KeyStacktrace, fmt.Sprintf("%+v", err))
        }
        return false // still proceed with normal error logging for exit handling
    }

    return false
}

3.4 Codebase-Wide Import Replacement¶

Every file that currently imports github.com/go-errors/errors will be updated to import github.com/cockroachdb/errors. The following API mappings apply:

3.5 Files Requiring Changes¶

The following non-test source files require import and API updates:

pkg/ (public library — highest priority):

cmd/ (built-in commands):

internal/ (generator and agent — lowest priority):

Test files (all *_test.go files that import go-errors):

Generated mocks:

3.6 Deprecation Cleanup¶

The existing deprecated package-level functions and variables will be retained in this migration but updated to use cockroachdb/errors internally. They remain deprecated:

• Logger (package var)
• Help (package var)
• OutputWriter (package var)
• Check() (package func)
• CheckFatal() (package func)
• CheckError() (package func)
• CheckWarn() (package func)
• SetHelp() (package func)

4. Project Structure¶

4.1 Modified Files¶

No new packages or directories are created. This is a migration within existing files.

pkg/errorhandling/
├── handling.go          # Core changes: import swap, enhanced logError, handleSpecialErrors
├── handling_test.go     # Rewritten tests
├── handling_debug_test.go  # Updated debug tests
├── options.go           # NEW: functional options for New()
└── helpers.go           # NEW: convenience wrappers (WithUserHint, NewAssertionFailure, etc.)

4.2 Dependency Changes¶

Added:

github.com/cockroachdb/errors  (latest stable, currently v1.12.0)

Removed:

github.com/go-errors/errors    v1.5.1

Transitive dependencies: cockroachdb/errors brings in github.com/cockroachdb/redact, github.com/cockroachdb/logtags, github.com/getsentry/sentry-go, and protobuf dependencies. While these increase the dependency tree, they are well-maintained and widely used in production Go systems. The Sentry dependency is optional and will not be used unless explicitly configured in a future enhancement.

5. Generator Impact¶

The internal/generator/ package uses go-errors for error creation and wrapping in the scaffolding logic. The migration here is mechanical (import swap + API mapping) and does not affect the generated output for downstream CLI projects.

However, the skeleton templates (in internal/generator/assets/skeleton/) should be reviewed to ensure that any error handling patterns in generated code reference cockroachdb/errors rather than go-errors. If the skeleton templates contain go-errors imports, they must be updated.

6. Error Handling Patterns (Post-Migration)¶

6.1 Creating Errors¶

import "github.com/cockroachdb/errors"

// Sentinel errors (package level)
var (
    ErrConfigNotFound = errors.New("configuration file not found")
    ErrInvalidPort    = errors.New("invalid port: must be between 1 and 65535")
)

// Inline errors with formatting
err := errors.Newf("unsupported provider: %s", provider)

// Wrapping with context
return errors.Wrap(err, "failed to load config")

// Wrapping with formatted context
return errors.Wrapf(err, "failed to process file %s", path)

6.2 Attaching User-Facing Hints¶

// Attach a hint to guide the user
err := errors.New("database connection failed")
err = errors.WithHint(err, "Check that the database server is running and the connection string is correct.")

// Or combine wrapping with a hint
return errorhandling.WrapWithHint(err, "database init failed",
    "Verify the DATABASE_URL environment variable is set correctly.")

6.3 Assertion Failures¶

// When an invariant is violated
if idx < 0 || idx >= len(items) {
    return errors.AssertionFailedf("index %d out of bounds [0, %d)", idx, len(items))
}

// Using the convenience wrapper
return errorhandling.NewAssertionFailure("unexpected nil config after validation")

6.4 Wrapping vs WithStack¶

// When adding context to an error — use Wrap
return errors.Wrap(err, "failed to read manifest")

// When re-returning an error without additional context — use WithStack
// (captures a stack trace at this point for debugging)
return errors.WithStack(err)

// When returning a sentinel with a stack trace
return errors.WithStack(ErrConfigNotFound)

6.5 Multi-Error Handling¶

// Combining errors from concurrent operations
errA := operationA()
errB := operationB()
return errors.CombineErrors(errA, errB)

6.6 Error Handling in Commands (unchanged pattern)¶

Run: func(cmd *cobra.Command, args []string) {
    props.ErrorHandler.Fatal(doWork(props))
},

The command-level error handling pattern is unchanged. The ErrorHandler now provides richer output automatically.

7. Testing Strategy¶

This migration follows a strict TDD approach. Tests are written first for each phase, then implementation is done to make them pass.

7.1 Unit Tests for pkg/errorhandling¶

7.1.1 StandardErrorHandler Core Behaviour¶

7.1.2 Stack Trace Behaviour¶

7.1.3 Hint and Detail Display¶

7.1.4 Special Error Handling¶

7.1.5 Help Configuration¶

7.1.6 Constructor and Options¶

7.1.7 Convenience Helpers¶

7.1.8 Backwards Compatibility¶

7.2 Integration Tests¶

7.3 Codebase-Wide Regression Tests¶

After the migration, the full test suite (go test -race ./...) must pass. No new test files are needed for the mechanical import-swap changes in pkg/, cmd/, and internal/ — the existing tests validate that error creation and wrapping behaviour is preserved.

7.4 Test Structure¶

All new tests follow project conventions:

• Table-driven tests where applicable
• Parallel execution (t.Parallel())
• bytes.Buffer capture for log output verification
• Mock exit functions for Fatal testing
• testify/assert for assertions
• >90% coverage target for pkg/errorhandling

8. Migration & Compatibility¶

8.1 Backwards Compatibility¶

8.2 Breaking Changes¶

This migration introduces no breaking changes to the public API surface (pkg/). The ErrorHandler interface, constructor signatures, sentinel errors, and all exported types remain compatible.

The only potentially breaking change is for downstream consumers who: 1. Import github.com/go-errors/errors independently and perform type assertions on errors returned by GTB functions. This is an uncommon pattern and can be addressed in release notes.

8.3 Versioning¶

This is a minor version bump (backward-compatible enhancement). The new dependency (cockroachdb/errors) is an addition, and the removal of go-errors does not affect the public API.

8.4 Migration Guide for Downstream Consumers¶

A section should be added to docs/upgrading/ with the following guidance:

1. Replace github.com/go-errors/errors imports with github.com/cockroachdb/errors.
2. Replace errors.WrapPrefix(err, "msg", 0) with errors.Wrap(err, "msg").
3. Replace errors.Wrap(err, 0) with errors.WithStack(err).
4. Replace .ErrorStack() calls with fmt.Sprintf("%+v", err).
5. Replace errors.Errorf(...) with errors.Newf(...) (or keep errors.Errorf — both work).
6. Add errors.WithHint(err, "hint") where user-facing suggestions are appropriate.

9. Documentation Updates¶

The following documentation files must be updated to reflect the new error library:

10. Future Considerations¶

The following items are out of scope for this specification but are enabled by the migration:

1. Sentry integration: cockroachdb/errors has built-in Sentry reporting via errors.BuildSentryReport(). A future spec could add opt-in crash reporting.
2. Error domains: Attaching package-origin domains to errors for better triage in large systems.
3. Telemetry keys: Attaching telemetry metadata to errors for observability pipelines.
4. Network portability: Encoding/decoding errors via protobuf for distributed CLI tooling scenarios.
5. PII-safe reporting: Leveraging errors.Safe() and GetSafeDetails() for automated PII stripping in log aggregation.
6. Custom error types with protobuf encoding: Building domain-specific error types (e.g. ValidationError, ConfigError) that are network-portable.

11. Implementation Phases¶

Phase 1: Core errorhandling Package Migration¶

Scope: pkg/errorhandling/ only.

Steps (TDD):

1. Write all unit tests from section 7.1 (they will fail — cockroachdb/errors is not yet imported).
2. Add github.com/cockroachdb/errors to go.mod.
3. Create pkg/errorhandling/options.go with functional options types.
4. Create pkg/errorhandling/helpers.go with convenience functions.
5. Update pkg/errorhandling/handling.go:
6. Replace import.
7. Update Check / logError / handleSpecialErrors.
8. Add new KeyHints / KeyDetails constants.
9. Update New constructor to accept options.
10. Verify all tests pass.
11. Regenerate mocks with mockery.
12. Run golangci-lint run --fix.

Acceptance criteria: - All section 7.1 tests pass. - go test -race ./pkg/errorhandling/... succeeds. - Coverage >= 90% for pkg/errorhandling.

Phase 2: Public Library Package Migration (pkg/)¶

Scope: All pkg/ packages except pkg/errorhandling/ (already done in Phase 1).

Steps (TDD):

1. For each package (config, props, chat, docs, setup, vcs, controls): a. Update existing tests to use cockroachdb/errors imports. b. Run tests — they should fail where go-errors-specific APIs are used. c. Update source files with the API mappings from section 3.4. d. Verify tests pass.
2. Where appropriate, enhance error returns with errors.WithHint for user-facing errors (e.g. config loading failures, GitHub authentication errors, AI provider errors).
3. Run go test -race ./pkg/....
4. Run golangci-lint run --fix ./pkg/....

Acceptance criteria: - All existing pkg/ tests pass with cockroachdb/errors. - No remaining imports of github.com/go-errors/errors in pkg/. - User-facing errors in config, setup, and chat packages include hints where appropriate.

Phase 3: Command and Internal Package Migration (cmd/, internal/)¶

Scope: cmd/root/, cmd/docs/, internal/generator/, internal/agent/, internal/cmd/.

Steps (TDD):

1. Update existing tests to use cockroachdb/errors imports.
2. Update source files with the API mappings from section 3.4.
3. Review skeleton templates in internal/generator/assets/skeleton/ for go-errors references and update.
4. Run go test -race ./cmd/... ./internal/....
5. Run golangci-lint run --fix ./cmd/... ./internal/....

Acceptance criteria: - All existing cmd/ and internal/ tests pass with cockroachdb/errors. - No remaining imports of github.com/go-errors/errors anywhere in the codebase.

Phase 4: Cleanup and Documentation¶

Scope: Dependency removal, documentation, migration guide.

Steps:

1. Remove github.com/go-errors/errors from go.mod and run go mod tidy.
2. Run mockery to regenerate all mocks.
3. Run full verification: go test -race ./..., golangci-lint run --fix.
4. Update all documentation files listed in section 9.
5. Create migration guide in docs/upgrading/.
6. Update .agent/skills/ and .agent/workflows/ files.

Acceptance criteria: - github.com/go-errors/errors does not appear in go.mod or go.sum. - Full test suite passes: go test -race ./.... - Linter passes: golangci-lint run. - All documentation references cockroachdb/errors. - Migration guide exists in docs/upgrading/. - The Verification Checklists are fully satisfied.