errors

Documentation

Overview

Package errors defines a typed error taxonomy for Helix's MCP tools.

Import convention: use alias "serr" to avoid shadowing stdlib errors.

import serr "github.com/agenthands/helix/internal/errors"

Index

• Variables
• type Error
  • func New(kind Kind, message string) *Error
  • func Wrap(kind Kind, message string, cause error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) MarshalJSON() ([]byte, error)
  • func (e *Error) Unwrap() error
  • func (e *Error) WithDetail(detail string) *Error
  • func (e *Error) WithTool(tool string) *Error
• type Kind

Variables

var (
	ErrNotFound    = &Error{Kind: NotFound}
	ErrInvalidArgs = &Error{Kind: InvalidArgs}
	ErrNoWorkspace = &Error{Kind: NoWorkspace}
	ErrUnsupported = &Error{Kind: Unsupported}
	ErrInternal    = &Error{Kind: Internal}
	ErrCircuitOpen = &Error{Kind: CircuitOpen}
	ErrTimeout     = &Error{Kind: Timeout}
)

Sentinel errors for use with errors.Is. Each sentinel carries only a Kind; Error.Is() compares Kind values, so errors.Is(err, ErrNotFound) matches any *Error with Kind == NotFound.

Types

type Error

type Error struct {
	Kind    Kind   `json:"kind"`
	Message string `json:"message"`
	Tool    string `json:"tool,omitempty"`
	Detail  string `json:"detail,omitempty"`
	// contains filtered or unexported fields
}

Error is the structured error type for all Helix MCP tools. It carries a Kind for programmatic matching, a human-readable Message, an optional Tool name, an optional Detail string, and an unexported cause for error chain traversal.

CRITICAL: Functions returning the error interface must never assign a *Error nil pointer to a variable and return it. Always return nil directly. A typed nil *Error satisfies error as non-nil, causing false positives.

func New

func New(kind Kind, message string) *Error

New creates a typed error with the given Kind and message.

func Wrap

func Wrap(kind Kind, message string, cause error) *Error

Wrap creates a typed error that wraps a cause error, preserving the error chain for errors.Is and errors.As traversal.

func (*Error) Error

func (e *Error) Error() string

Error returns a human-readable string: "kind: message" or "kind: message (detail)" when Detail is non-empty.

func (*Error) Is

func (e *Error) Is(target error) bool

Is enables errors.Is matching by Kind. When the target is an *Error, it matches if both errors share the same Kind value. This allows sentinel-based matching: errors.Is(err, serr.ErrNotFound).

func (*Error) MarshalJSON

func (e *Error) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of the Error. Uses a type alias to prevent infinite recursion through the json.Marshaler interface.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying cause error for error chain traversal.

func (*Error) WithDetail

func (e *Error) WithDetail(detail string) *Error

WithDetail sets the detail string on the error and returns the same *Error for builder-style chaining.

func (*Error) WithTool

func (e *Error) WithTool(tool string) *Error

WithTool sets the tool name on the error and returns the same *Error for builder-style chaining.

type Kind

type Kind string

Kind classifies errors for programmatic matching by agents. Callers check Kind via errors.Is(err, serr.ErrNotFound) rather than string matching on error messages.

const (
	NotFound    Kind = "not_found"
	InvalidArgs Kind = "invalid_args"
	NoWorkspace Kind = "no_workspace"
	Unsupported Kind = "unsupported"
	Internal    Kind = "internal"
	CircuitOpen Kind = "circuit_open"
	Timeout     Kind = "timeout"
)