What causes "Invalid ValueLogFileSize, must be in range [1MB, 2GB)" in dgraph-io/badger?

Set ValueLogFileSize within [1MB, 2GB), e.g. WithValueLogFileSize(1<<30) for 1GB

ErrValueLogSize

ErrValueLogSize

Error message

Invalid ValueLogFileSize, must be in range [1MB, 2GB)

What it means

ErrValueLogSize is returned by Badger's checkAndSetOptions during Open() when the ValueLogFileSize option is outside [1MB, 2GB). The upper bound exists because the value log file is mmapped and its size must fit in a uint32 (db.go:179); the lower bound is the smallest supported file size.

Source

Thrown at errors.go:21

 * SPDX-License-Identifier: Apache-2.0
 */

package badger

import (
	stderrors "errors"
	"math"
)

const (
	// ValueThresholdLimit is the maximum permissible value of opt.ValueThreshold.
	ValueThresholdLimit = math.MaxUint16 - 16 + 1
)

var (
	// ErrValueLogSize is returned when opt.ValueLogFileSize option is not within the valid
	// range.
	ErrValueLogSize = stderrors.New("Invalid ValueLogFileSize, must be in range [1MB, 2GB)")

	// ErrKeyNotFound is returned when key isn't found on a txn.Get.
	ErrKeyNotFound = stderrors.New("Key not found")

	// ErrTxnTooBig is returned if too many writes are fit into a single transaction.
	ErrTxnTooBig = stderrors.New("Txn is too big to fit into one request")

	// ErrConflict is returned when a transaction conflicts with another transaction. This can
	// happen if the read rows had been updated concurrently by another transaction.
	ErrConflict = stderrors.New("Transaction Conflict. Please retry")

	// ErrReadOnlyTxn is returned if an update function is called on a read-only transaction.
	ErrReadOnlyTxn = stderrors.New("No sets or deletes are allowed in a read-only transaction")

	// ErrDiscardedTxn is returned if a previously discarded transaction is reused.
	ErrDiscardedTxn = stderrors.New("This transaction has been discarded. Create a new one")

	// ErrEmptyKey is returned if an empty key is passed on an update function.

View on GitHub (pinned to 2a001d466f)

Solutions

Set ValueLogFileSize within [1MB, 2GB), e.g. WithValueLogFileSize(1<<30) for 1GB
Cap large sizes at 2<<30 - 1 and accept more value log files
Validate options before Open() so you fail with your own message

Example fix

// before
opts := badger.DefaultOptions(dir).WithValueLogFileSize(4 << 30) // ErrValueLogSize
// after
opts := badger.DefaultOptions(dir).WithValueLogFileSize(1 << 30) // 1GB, valid

Defensive patterns

Strategy: validation

Validate before calling

if vlfSize < 1<<20 || vlfSize >= 2<<30 {
    return fmt.Errorf("ValueLogFileSize must be in [1MB, 2GB), got %d", vlfSize)
}

Try / catch

err := badger.Open(opts)
if errors.Is(err, badger.ErrValueLogSize) {
    // clamp and retry
    opts.ValueLogFileSize = 1 << 30
    db, err = badger.Open(opts)
}

Prevention

Keep ValueLogFileSize between 1MB and 2GB; default (2GB-bound defaults) is usually fine
Call opts.Validate() before Open()
Centralize option construction in one helper so bounds are enforced once

When it happens

Trigger: Calling badger.Open/OpenManaged with opt.ValueLogFileSize < 1<<20 or >= 2<<30, e.g. WithValueLogFileSize(4<<30) or WithValueLogFileSize(512<<10).

Common situations: Trying to make value logs tiny to save disk (below 1MB), or huge (4GB/10GB) to reduce file counts, forgetting the 2GB hard cap.

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

AI-assisted analysis of dgraph-io/badger@2a001d466f (2026-09-05). Data as JSON: /api/errors/40340cc6b9893c15. Report an issue: GitHub.