benbjohnson/litestream · error

unknown config key: %s

Error message

unknown config key: %s

What it means

VFSConfig.Set only accepts a fixed set of keys (write_enabled, sync_interval, buffer_path, hydration_enabled, hydration_path, poll_interval, cache_size, etc.). Any other key hits the default branch and is rejected, preventing silent typos in VFS URI parameters.

Source

Thrown at vfs_config.go:92

	case "hydration_enabled":
		b := strings.ToLower(value) == "true" || value == "1"
		cfg.HydrationEnabled = &b
	case "hydration_path":
		cfg.HydrationPath = value
	case "poll_interval":
		d, err := time.ParseDuration(value)
		if err != nil {
			return fmt.Errorf("invalid poll_interval: %w", err)
		}
		cfg.PollInterval = &d
	case "cache_size":
		n, err := strconv.Atoi(value)
		if err != nil {
			return fmt.Errorf("invalid cache_size: %w", err)
		}
		cfg.CacheSize = &n
	default:
		return fmt.Errorf("unknown config key: %s", key)
	}
	return nil
}

func ParseVFSURIConfig(uriParameters map[string]string) (*VFSConfig, error) {
	if len(uriParameters) == 0 {
		return nil, nil
	}

	cfg := &VFSConfig{}
	var found bool
	for _, key := range vfsURIConfigKeys {
		value, ok := uriParameters[key]
		if !ok {
			continue
		}
		if err := cfg.Set(key, value); err != nil {
			return nil, err

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check the supported key list and fix the spelling (e.g. sync_interval not syncinterval)
2. Remove unsupported parameters from the VFS URI
3. Consult the litestream VFS docs for the current version — option names change between releases

Example fix

// before
litestream://file:///db?syncinterval=10s
// after
litestream://file:///db?sync_interval=10s

var allowed = map[string]bool{"write_enabled":true,"sync_interval":true,"buffer_path":true,"hydration_enabled":true,"hydration_path":true,"poll_interval":true,"cache_size":true}
for k := range uriParams {
    if !allowed[k] { return fmt.Errorf("unsupported VFS param %q", k) }
}

if err := cfg.Set(k, v); err != nil {
    if strings.Contains(err.Error(), "unknown config key") {
        // list supported keys and fix the parameter name
    }
}

When it happens

Trigger: Calling Set(<key>, <value>) — typically via ParseVFSURIConfig on URI query parameters — with a key outside the supported set, e.g. sync_interval misspelled as syncinterval, or an unrelated param left in the URI.

Common situations: Typo'd parameter names in the litestream VFS URI; parameters copied from a different driver's URI; stale options removed in a newer litestream version.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• invalid sync_interval: %w
• invalid poll_interval: %w
• invalid cache_size: %w
• snapshot interval must be greater than 0
• snapshot retention must be greater than 0

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/325ccc29ceb5b3af. Report an issue: GitHub.