benbjohnson/litestream · error

size %d exceeds maximum allowed value (%d)

Error message

size %d exceeds maximum allowed value (%d)

What it means

ParseByteSize guards that the parsed unsigned value fits in an int64. go-humanize returns uint64, so astronomically large values (e.g. "20EiB") exceed math.MaxInt64 and are rejected rather than silently overflowing negative.

Source

Thrown at cmd/litestream/main.go:1105

// 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.
type ReplicaSettings struct {
	SyncInterval       *time.Duration `yaml:"sync-interval"`
	ValidationInterval *time.Duration `yaml:"validation-interval"`

	// Maximum L0 files to upload in a single monitor sync run.
	// Set to zero to process all pending L0 files in one run.
	MaxSyncLTXFiles *int `yaml:"max-sync-ltx-files"`

	// If true, automatically reset local state when LTX errors are detected.
	// This allows recovery from corrupted/missing LTX files by forcing a fresh sync.
	// Disabled by default to prevent silent data loss scenarios.

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Use a realistic size below 8 EiB (int64 max bytes)
2. If the intent is 'no limit', omit the field or use the documented default rather than a huge value
3. Verify the value after unit parsing: "1000000TB" still overflows

Example fix

# before
max-size: 20EiB
# after
max-size: 1TB

if n, err := humanize.ParseBytes(cfg.Size); err == nil && n > math.MaxInt64 {
    return fmt.Errorf("size %q exceeds int64 max", cfg.Size)
}

When it happens

Trigger: A size config value parses successfully but is larger than 9223372036854775807 bytes, e.g. "10EB", "9223372036854775808", "20EiB".

Common situations: Copy-pasted placeholder or sentinel values like "9999999999999999999GB"; a user trying to express "unlimited" as a huge size.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• empty size string
• invalid size format: %w
• heartbeat URL must be a valid HTTP or HTTPS URL
• heartbeat interval must be at least 1 minute
• config file not found

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