What causes "empty size string" in benbjohnson/litestream?

Set an explicit size value like "1GB" or "5MiB" on the config key

empty size string

Error message

empty size string

What it means

ParseByteSize rejected its input because after trimming whitespace the string was empty. The ByteSize UnmarshalText path handed it a valueless config/flag token such as an empty retention or size field.

Source

Thrown at cmd/litestream/main.go:1094

	if err := unmarshal(&s); err != nil {
		return err
	}

	size, err := ParseByteSize(s)
	if err != nil {
		return err
	}
	*b = ByteSize(size)
	return nil
}

// ParseByteSize parses a byte size string using github.com/dustin/go-humanize.
// Supports both SI units (KB=1000, MB=1000², etc.) and IEC units (KiB=1024, MiB=1024², etc.).
// Examples: "1MB", "5MiB", "1.5GB", "100B", "1024KB"
func ParseByteSize(s string) (int64, error) {
	s = strings.TrimSpace(s)
	if s == "" {
		return 0, fmt.Errorf("empty size string")
	}

	// Use go-humanize to parse the byte size string
	bytes, err := humanize.ParseBytes(s)
	if err != nil {
		return 0, fmt.Errorf("invalid size format: %w", err)
	}

	// Check that the value fits in int64
	if bytes > math.MaxInt64 {
		return 0, fmt.Errorf("size %d exceeds maximum allowed value (%d)", bytes, int64(math.MaxInt64))
	}

	return int64(bytes), nil
}

// ReplicaSettings contains settings shared across replica configurations.
// These can be set globally in Config or per-replica in ReplicaConfig.

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set an explicit size value like "1GB" or "5MiB" on the config key
Remove the empty key to use the built-in default instead
Check that any env var used in the value is actually set at launch

Example fix

# before
retention: ""
# after
retention: 24h  # or use a size key: size: 1GB

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(cfg.Size) == "" {
    return errors.New("size must be set, e.g. \"1GB\"")
}

Prevention

Never leave size keys with empty values; delete the key to use defaults
Verify env vars referenced in config values are set at launch
Validate the full config file at startup before deploy

When it happens

Trigger: A config field expecting a byte size (parsed via ParseByteSize) is set to "" or only whitespace, e.g. `retention-check-interval: ""` or an env-var expansion that resolved to empty.

Common situations: YAML key present with empty value; `${SIZE_ENV}` unset so it expands to an empty string; quoted empty string left over from editing.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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