ErrTruncateNeeded

ErrTruncateNeeded

Error message

Log truncate required to run DB. This might result in data loss

What it means

ErrTruncateNeeded is returned when the value log (or memtable WAL) is corrupt and Badger requires truncation of the corrupt tail data to run, which may result in data loss. In read-only mode Badger cannot perform the truncation itself, so replay fails (memtable.go:210 wraps it with offset details). Defined in errors.go as a sentinel error.

Source

Thrown at errors.go:89

	// NamespaceOffset is non-negative.
	ErrNamespaceMode = stderrors.New(
		"Invalid API request. Not allowed to perform this action when NamespaceMode is not set.")

	// ErrInvalidDump if a data dump made previously cannot be loaded into the database.
	ErrInvalidDump = stderrors.New("Data dump cannot be read")

	// ErrZeroBandwidth is returned if the user passes in zero bandwidth for sequence.
	ErrZeroBandwidth = stderrors.New("Bandwidth must be greater than zero")

	// ErrWindowsNotSupported is returned when opt.ReadOnly is used on Windows
	ErrWindowsNotSupported = stderrors.New("Read-only mode is not supported on Windows")

	// ErrPlan9NotSupported is returned when opt.ReadOnly is used on Plan 9
	ErrPlan9NotSupported = stderrors.New("Read-only mode is not supported on Plan 9")

	// ErrTruncateNeeded is returned when the value log gets corrupt, and requires truncation of
	// corrupt data to allow Badger to run properly.
	ErrTruncateNeeded = stderrors.New(
		"Log truncate required to run DB. This might result in data loss")

	// ErrBlockedWrites is returned if the user called DropAll. During the process of dropping all
	// data from Badger, we stop accepting new writes, by returning this error.
	ErrBlockedWrites = stderrors.New("Writes are blocked, possibly due to DropAll or Close")

	// ErrNilCallback is returned when subscriber's callback is nil.
	ErrNilCallback = stderrors.New("Callback cannot be nil")

	// ErrEncryptionKeyMismatch is returned when the storage key is not
	// matched with the key previously given.
	ErrEncryptionKeyMismatch = stderrors.New("Encryption key mismatch")

	// ErrInvalidDataKeyID is returned if the datakey id is invalid.
	ErrInvalidDataKeyID = stderrors.New("Invalid datakey id")

	// ErrInvalidEncryptionKey is returned if length of encryption keys is invalid.
	ErrInvalidEncryptionKey = stderrors.New("Encryption key's length should be" +

View on GitHub (pinned to 2a001d466f)

Solutions

Open the DB in read-write mode once so Badger can truncate the corrupt data automatically
Back up the data directory before allowing truncation, since tail data may be lost
If data loss is unacceptable, run value-log recovery tooling (e.g. bank/restore-like tools) before opening
Investigate why the WAL was truncated/corrupt: unclean shutdown, disk full, or improper file copy

Example fix

// before
opts = append(opts, badger.WithReadOnly(true))
db, err := badger.Open(opts...) // ErrTruncateNeeded
// after
// open read-write once to let badger truncate the corrupt tail
db, err := badger.Open(opts) // no WithReadOnly
if err != nil { return err }
db.Close()
// now safe to open read-only
opts = append(opts, badger.WithReadOnly(true))
db, err = badger.Open(opts...)

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check: inspect MANIFEST/WAL tail integrity, or attempt read-write open first on suspected corruption

Type guard

func isTruncateNeeded(err error) bool { return errors.Is(err, ErrTruncateNeeded) }

Try / catch

db, err := badger.Open(opts)
if errors.Is(err, ErrTruncateNeeded) {
	// back up directory, then reopen WITHOUT ReadOnly so badger can truncate
}

Prevention

Back up the DB directory before opening a suspect DB read-only
Use clean shutdown paths and fsync-aware file copying
Monitor for unclean shutdowns and disk-full events
Copy DB files only while the DB is closed or via the Stream/Backup APIs

When it happens

Trigger: Opening a DB in ReadOnly mode whose memtable WAL contains records beyond the replay end offset (endOff < wal.size) — memtable.go:210 returns y.Wrapf(ErrTruncateNeeded, ...); generally any detected value-log corruption needing tail truncation.

Common situations: Machine crash or power loss leaving a partially written WAL; copying DB files without flush while running; opening a corrupted DB read-only (e.g. for recovery tools) and hitting the truncation requirement.

Related errors

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