dgraph-io/badger · error

ErrThresholdZero

ErrThresholdZero

Error message

Value log GC can't run because threshold is set to zero

What it means

ErrThresholdZero is returned by value log GC APIs (db.RunValueLogGC) when the GC threshold option is zero. With a zero threshold the GC cannot decide which files are candidates, so Badger refuses to run it (errors.go:51).

Source

Thrown at errors.go:51

	// 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.
	ErrEmptyKey = stderrors.New("Key cannot be empty")

	// ErrInvalidKey is returned if the key has a special !badger! prefix,
	// reserved for internal usage.
	ErrInvalidKey = stderrors.New("Key is using a reserved !badger! prefix")

	// ErrBannedKey is returned if the read/write key belongs to any banned namespace.
	ErrBannedKey = stderrors.New("Key is using the banned prefix")

	// ErrThresholdZero is returned if threshold is set to zero, and value log GC is called.
	// In such a case, GC can't be run.
	ErrThresholdZero = stderrors.New(
		"Value log GC can't run because threshold is set to zero")

	// ErrNoRewrite is returned if a call for value log GC doesn't result in a log file rewrite.
	ErrNoRewrite = stderrors.New(
		"Value log GC attempt didn't result in any cleanup")

	// ErrRejected is returned if a value log GC is called either while another GC is running, or
	// after DB::Close has been called.
	ErrRejected = stderrors.New("Value log GC request rejected")

	// ErrInvalidRequest is returned if the user request is invalid.
	ErrInvalidRequest = stderrors.New("Invalid request")

	// ErrManagedTxn is returned if the user tries to use an API which isn't
	// allowed due to external management of transactions, when using ManagedDB.
	ErrManagedTxn = stderrors.New(
		"Invalid API request. Not allowed to perform this action using ManagedDB")

View on GitHub (pinned to 2a001d466f)

Solutions

1. Call db.RunValueLogGC with a valid percentage in (0, 100), e.g. 0.5 for 50% discardable space
2. Open the DB with a non-zero GC threshold option if GC is part of your maintenance routine
3. Skip manual vlog GC and rely on automatic vlog GC (default in newer Badger)

Example fix

// before
err := db.RunValueLogGC(0) // ErrThresholdZero
// after
err := db.RunValueLogGC(0.5) // rewrite when >50% of the file is discardable

if gcPercent <= 0 || gcPercent >= 100 {
    return errors.New("RunValueLogGC needs a percent in (0, 100)")
}

if err := db.RunValueLogGC(pct); err != nil {
    if errors.Is(err, badger.ErrThresholdZero) {
        return fmt.Errorf("enable a non-zero GC threshold before running vlog GC")
    }
    return err
}

When it happens

Trigger: Calling db.RunValueLogGC(0) on a DB opened with WithCheckpointerMode/WithGC-related options where the discard/GC threshold (e.g. opt.CheckpointerOptions or vlog GC threshold) is 0; in modern Badger, RunValueLogGC(percent) with percentage < 1 behaves as a zero threshold.

Common situations: Operators running GC against a DB configured with thresholds disabled, or passing 0 as the rewrite percentage by mistake.

Related errors

• ErrValueLogSize
• ErrNoRewrite
• ErrRejected
• ErrInvalidRequest
• ErrNamespaceMode

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