Skip to content

Errors & logging

On this page

Error types and the named structured loggers.

struct `ArgumentError`

type ArgumentError struct {
ArgName    string
Position  int  // -1 when name-only
Detail    string
}

Description

ArgumentError is returned when a function argument is missing, of the wrong shape, or fails inline validation at bind/init time. Use it from inside OnBind/OnBindTyped to surface a clean error to the caller rather than the generic “RuntimeError: …” default.

Methods

method `Error`

func (e *ArgumentError) Error() string

Error implements the error interface.

struct `CatalogReadOnlyError`

type CatalogReadOnlyError struct {
Operation string
}

Description

CatalogReadOnlyError is returned when a write operation is attempted on a read-only catalog.

Methods

method `Error`

func (e *CatalogReadOnlyError) Error() string

Error implements the error interface.

type `LogFormat`

type LogFormat string

Description

LogFormat selects the stderr log format.

struct `LoggingConfig`

type LoggingConfig struct {
// Level is the minimum level for enabled loggers. Default Info.
Level  slog.Level
// Format selects the stderr formatter. Default text.
Format  LogFormat
// Output is where records are written. Default os.Stderr.
Output  io.Writer
// Loggers restricts which named loggers emit records. Empty means
// "all known loggers". Unknown names are passed through with a warning
// on stderr (matching vgi-python's behaviour).
Loggers  []string
// Debug forces Level to Debug regardless of the explicit Level value.
// Mirrors vgi-python's --debug shortcut.
Debug  bool
}

Description

LoggingConfig describes the desired logging setup for a worker.

Methods

method `effectiveLevel`

func (c LoggingConfig) effectiveLevel() slog.Level

effectiveLevel returns the level after applying the Debug shortcut.

struct `LoggingFlags`

type LoggingFlags struct {
debug    *bool
level    *string
format    *string
loggers    *string
loggerSet  *stringSliceFlag
}

Description

LoggingFlags holds the values parsed from the standard logging CLI flags. Resolve it into a LoggingConfig with .Config().

Methods

method `Apply`

func (lf *LoggingFlags) Apply() error

Apply parses, validates, and installs the logging configuration in one step. Convenience wrapper for the common case where a worker main() just wants “honor the flags”.

method `Config`

func (lf *LoggingFlags) Config() (LoggingConfig, error)

Config resolves the parsed flags into a LoggingConfig. Call after fs.Parse(). Returns an error if a flag value is malformed.

function `RegisterLoggingFlags`

func RegisterLoggingFlags(fs *flag.FlagSet) *LoggingFlags

RegisterLoggingFlags registers –debug, –log-level, –log-format, and –log-logger on the given FlagSet. The returned LoggingFlags resolves to a LoggingConfig after Parse() runs. Env-var defaults: VGI_LOG_LEVEL, VGI_LOG_FORMAT, VGI_LOG_LOGGER. VGI_WORKER_DEBUG=1 enables –debug.

struct `SchemaFieldMismatch`

type SchemaFieldMismatch struct {
FieldName  string
Expected  arrow.DataType  // nil when missing on the expected side
Actual    arrow.DataType  // nil when missing on the actual side
Reason    string    // optional — overrides the default phrasing
}

Description

SchemaFieldMismatch is one field-level disagreement between two schemas.

struct `SchemaValidationError`

type SchemaValidationError struct {
Context    string  // e.g. "table function output schema"
Mismatches  []SchemaFieldMismatch
}

Description

SchemaValidationError describes one or more field-level type mismatches between an expected schema and an actual schema. The message lists each mismatched field with expected vs. actual types — analogous to vgi-python’s SchemaValidationError.

Methods

method `Error`

func (e *SchemaValidationError) Error() string

Error implements the error interface.

struct `TypeBoundError`

type TypeBoundError struct {
ArgName    string
Position  int
FieldType  arrow.DataType
// PredicateNames are the runtime-resolved names of the failed predicates,
// e.g. ["IsMultipliableType"]. Empty when reflection couldn't recover them.
PredicateNames  []string
}

Description

TypeBoundError is returned when an input schema field type does not satisfy the type bound predicates declared for an argument.

Methods

method `Error`

func (e *TypeBoundError) Error() string

Error implements the error interface.

struct `UnknownFunctionError`

type UnknownFunctionError struct {
Name    string
FunctionType  string
}

Description

UnknownFunctionError is returned when a function name cannot be resolved.

Methods

method `Error`

func (e *UnknownFunctionError) Error() string

Error implements the error interface.

struct `WorkerPanicError`

type WorkerPanicError struct {
FunctionName  string
Phase    string  // bind, init, process, finalize, etc.
Recovered  any  // value passed to panic()
Stack    []byte
}

Description

WorkerPanicError is returned when a registered function panics during bind/init/process/finalize. The dispatcher (see RecoverPanic) catches the panic, captures the stack, and returns this error to the caller so the worker process stays alive and the RPC client sees a clean message.

Methods

method `Error`

func (e *WorkerPanicError) Error() string

Error implements the error interface.

struct `loggerFilterHandler`

type loggerFilterHandler struct {
base    slog.Handler
enabled    map[string]struct{}
loggerName  string  // captured via WithAttrs (slog.With("logger", X))
}

Description

loggerFilterHandler wraps a base handler and drops records emitted by a named logger (logger=…) that is not in the enabled set. The name is captured when a logger is constructed via slog.New(…).With(“logger”, N), which routes through WithAttrs — we extract and remember the value, and also keep checking the per-record attributes so direct calls like slog.Info(“…”, “logger”, “vgi.foo”) still filter correctly.

Records without any “logger” attribute always pass — they originate from code paths not migrated to the named loggers and we prefer not to silently swallow them.

Methods

method `Enabled`

func (h *loggerFilterHandler) Enabled(ctx context.Context, lvl slog.Level) bool

Enabled reports whether the underlying handler is enabled for the level; per-logger filtering happens later, in Handle.

method `Handle`

func (h *loggerFilterHandler) Handle(ctx context.Context, r slog.Record) error

Handle drops the record when its logger name is not in the enabled set, otherwise forwards it to the base handler.

method `WithAttrs`

func (h *loggerFilterHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a copy capturing any “logger” attribute so the name is known when filtering records.

method `WithGroup`

func (h *loggerFilterHandler) WithGroup(name string) slog.Handler

WithGroup returns a copy with the group applied to the base handler, preserving the captured logger name and enabled set.

method `allow`

func (h *loggerFilterHandler) allow(name string) bool

struct `stringSliceFlag`

type stringSliceFlag struct {
values []string
}

Description

stringSliceFlag is a flag.Value that accumulates repeatable –log-logger values. It also splits a single value on commas, so users can pass either “–log-logger=vgi.catalog –log-logger=vgi.rpc” or “–log-logger=vgi.catalog,vgi.rpc”.

Methods

method `Set`

func (s *stringSliceFlag) Set(v string) error

Set appends the comma-separated values in v, ignoring blank entries, to implement flag.Value for repeatable string flags.

method `String`

func (s *stringSliceFlag) String() string

function `AsRpcError`

func AsRpcError(err error) *vgirpc.RpcError

AsRpcError converts an error to an RpcError for wire transmission. Maps known custom error types to clearer Type strings so DuckDB-side error surfacing matches vgi-python’s behaviour.

function `ConfigureLogging`

func ConfigureLogging(cfg LoggingConfig)

ConfigureLogging installs a fresh root handler reflecting cfg and rebinds the package-level named loggers. Subsequent calls replace the configuration. Safe to call from main() before vgi.NewWorker(…).

function `ParseLogLevel`

func ParseLogLevel(s string) (slog.Level, error)

ParseLogLevel parses a level string (“debug”, “info”, “warn”, “error”, any case). Returns slog.LevelInfo for empty input. Returns an error on unknown values.

function `RecoverPanic`

func RecoverPanic(phase, fnName string, errOut *error)

RecoverPanic is meant to be deferred at the top of an RPC handler that may invoke user-supplied function code. On panic it stores a WorkerPanicError into *errOut so the framework returns a clean RpcError instead of crashing.

Usage:

func (w *Worker) handleBind(...) (resp BindResponseWire, err error) {
defer vgi.RecoverPanic("bind", req.FunctionName, &err)
...
}

function `envBool`

func envBool(name string) bool

function `parentLogger`

func parentLogger(name string) string

parentLogger returns the dotted parent of name, or “” at the root. “vgi.catalog” → “vgi”; “vgi” → “”.