Error Handling

Vault defines sentinel errors in the root vault package. Use errors.Is to check for specific error conditions in your application code.

Using errors.Is

import (
    "errors"
    "github.com/xraph/vault"
)

sec, err := secretSvc.Get(ctx, "my-key", "myapp")
if errors.Is(err, vault.ErrSecretNotFound) {
    // secret does not exist for this app
}

All Vault services return these sentinel errors. Store backends wrap them appropriately so that errors.Is works regardless of which backend is in use.

Sentinel errors by category

Store errors

Not-found errors

These are returned when a requested entity does not exist for the given key and app ID.

Cryptography errors

The crypto package also defines its own error:

crypto.ErrInvalidKeySize // "crypto: key must be exactly 32 bytes for AES-256"

Feature flag errors

Secret errors

Config errors

Rotation errors

Authorization errors

Source package errors

The source package defines its own not-found error:

source.ErrKeyNotFound // "source: key not found"

This is returned when no source in a chain contains the requested key. The source.Database adapter converts vault.ErrConfigNotFound to source.ErrKeyNotFound automatically.

Error handling patterns

Check for specific errors

sec, err := secretSvc.Get(ctx, "api-key", "myapp")
switch {
case errors.Is(err, vault.ErrSecretNotFound):
    // key does not exist -- create it
case err != nil:
    // unexpected error
default:
    // success
}

Flag evaluation with defaults

The type-safe flag.Service methods (Bool, String, Int, Float) return the default value on any error, including ErrFlagNotFound. This is intentional -- flag evaluation should never crash your application.

// Returns false (the default) if the flag does not exist, is disabled,
// or evaluation encounters any error.
enabled := flagSvc.Bool(ctx, "new-dashboard", false)

If you need to distinguish between "flag not found" and "flag exists but evaluates to default", use the Engine.Evaluate method directly:

val, err := engine.Evaluate(ctx, "new-dashboard", "myapp")
if errors.Is(err, vault.ErrFlagNotFound) {
    // flag definition does not exist
}

Config with fallback

Similarly, config.Service type-safe accessors return the default value on error:

// Returns 50 if "rate-limit" is not found or has a type mismatch.
limit := configSvc.Int(ctx, "rate-limit", 50)

Override resolution

The override.Resolver silently falls through when ErrOverrideNotFound is returned -- it returns the app-level config value instead. Only unexpected errors are propagated.

val, err := resolver.Resolve(ctx, "rate-limit", "myapp")
if errors.Is(err, vault.ErrConfigNotFound) {
    // neither override nor app config exists
}

Wrapped errors

Service methods may wrap sentinel errors with additional context using fmt.Errorf and %w. Always use errors.Is rather than string comparison:

// Works correctly even if the error is wrapped.
if errors.Is(err, vault.ErrSecretNotFound) {
    // ...
}