Types Reference

Error Types

FieldError

type FieldError struct {
    Field string
    Err   error
}

Wraps an error with field context.

Fields:

• Field — the struct field name where the error occurred
• Err — the underlying error

Methods:

func (e *FieldError) Error() string
func (e *FieldError) Unwrap() error

Usage:

err := fig.Load(&cfg)
if err != nil {
    var fieldErr *fig.FieldError
    if errors.As(err, &fieldErr) {
        fmt.Printf("Field: %s\n", fieldErr.Field)
        fmt.Printf("Cause: %v\n", fieldErr.Err)
    }
}

Example Output:

fig: field Password: fig: required field not set

Sentinel Errors

ErrRequired

var ErrRequired = errors.New("fig: required field not set")

Returned when a field marked required:"true" has no value from any source.

Wrapped in: FieldError

Check:

if errors.Is(err, fig.ErrRequired) {
    // Handle missing required field
}

ErrInvalidType

var ErrInvalidType = errors.New("fig: invalid type conversion")

Returned when a string value cannot be converted to the target type.

Wrapped in: FieldError

Common causes:

• Non-numeric string for int/float fields
• Invalid boolean string (not true, false, 1, 0, etc.)
• Invalid duration format
• Unsupported target type

Check:

if errors.Is(err, fig.ErrInvalidType) {
    // Handle type conversion failure
}

ErrNotStruct

var ErrNotStruct = errors.New("fig: type must be a struct")

Returned when Load is called with a non-struct type.

Not wrapped: Returned directly from Load.

Example:

var s string
err := fig.Load(&s)  // Returns ErrNotStruct

ErrSecretNotFound

var ErrSecretNotFound = errors.New("fig: secret not found")

Returned by secret providers when a secret doesn't exist.

Behaviour: When a provider returns this error, fig continues to the next source (env, then default). It only becomes a Load error if the field is required and no other source provides a value.

For provider implementers: Return this error only for missing secrets. Return other errors for network issues, permission denied, etc.

Supported Types

fig converts string values to these types:

Boolean Values

Accepted values for bool fields:

Duration Format

Duration strings use Go's time.ParseDuration format:

Examples: "100ms", "30s", "5m", "1h30m", "2h45m30s"

String Slices

Comma-separated values are split and trimmed:

Tags []string `env:"TAGS"`  // TAGS="api, v2, prod" → ["api", "v2", "prod"]

Empty parts are removed: "a,,b" → ["a", "b"]

TextUnmarshaler

Types implementing encoding.TextUnmarshaler are supported:

type LogLevel int

func (l *LogLevel) UnmarshalText(text []byte) error {
    switch string(text) {
    case "debug":
        *l = 0
    case "info":
        *l = 1
    case "warn":
        *l = 2
    case "error":
        *l = 3
    default:
        return fmt.Errorf("unknown log level: %s", text)
    }
    return nil
}

type Config struct {
    Level LogLevel `env:"LOG_LEVEL" default:"info"`
}

Pointer Types

Pointers to supported types are handled automatically:

type Config struct {
    Port    *int    `env:"PORT"`           // nil if unset
    Host    *string `env:"HOST"`           // nil if unset
    Timeout *time.Duration `env:"TIMEOUT"` // nil if unset
}

Use pointers to distinguish between "unset" and "zero value".

Unsupported Types

The following types return ErrInvalidType:

• Maps (map[K]V)
• Slices other than []string
• Channels
• Functions
• Complex numbers
• Interfaces (except encoding.TextUnmarshaler)

For complex types, consider JSON encoding:

type Config struct {
    SettingsJSON string `env:"SETTINGS"`
}

func (c *Config) Settings() (map[string]any, error) {
    var m map[string]any
    return m, json.Unmarshal([]byte(c.SettingsJSON), &m)
}

Next Steps

• API Reference — function signatures and interfaces
• Troubleshooting — common errors and debugging