dgraph-io/badger · error

%s. Path=%s. Error=%v

Error message

%s. Path=%s. Error=%v

What it means

errFile is badger's helper that wraps an underlying error with a message, the value log file path involved, and the original error. It is used when operations on a vlog file (open, iterate, populating the files map) fail so the developer can tell WHICH file caused the failure. The root cause (os.PathError, syscall errors, corruption) is preserved via %v and can be inspected from the error string.

Source

Thrown at value.go:556

		return nil, err
	}

	vlog.filesLock.Lock()
	vlog.filesMap[fid] = lf
	y.AssertTrue(vlog.maxFid < fid)
	vlog.maxFid = fid
	// writableLogOffset is only written by write func, by read by Read func.
	// To avoid a race condition, all reads and updates to this variable must be
	// done via atomics.
	vlog.writableLogOffset.Store(vlogHeaderSize)
	vlog.numEntriesWritten = 0
	vlog.filesLock.Unlock()

	return lf, nil
}

func errFile(err error, path string, msg string) error {
	return fmt.Errorf("%s. Path=%s. Error=%v", msg, path, err)
}

// init initializes the value log struct. This initialization needs to happen
// before compactions start.
func (vlog *valueLog) init(db *DB) {
	vlog.opt = db.opt
	vlog.db = db
	// We don't need to open any vlog files or collect stats for GC if DB is opened
	// in InMemory mode. InMemory mode doesn't create any files/directories on disk.
	if vlog.opt.InMemory {
		return
	}
	vlog.dirPath = vlog.opt.ValueDir

	if vlog.opt.ReadOnly {
		return
	}

View on GitHub (pinned to 2a001d466f)

Solutions

  1. Read the wrapped Error= text to find the root cause (permission denied, too many open files, no such file) and fix that condition.
  2. Raise ulimit -n (e.g. 65536) and ensure the badger directory and *.vlog files are readable/writable by the process user.
  3. Verify vlog files are intact and fully copied — never copy a live badger directory; stop the DB or use DB.Backup/DB.Load.
  4. If the file is genuinely corrupted, restore from backup or, accepting data loss, move the bad vlog file aside and reopen.
  5. Check disk space (df -h) and dmesg for underlying I/O errors.

Example fix

// before: copying a live DB directory then opening it
$ cp -r /var/lib/badger /backup && reopen /backup
// Error: ... Path=/backup/000001.vlog. Error=file truncated
// after: stop badger (or use backup API) before copying
err := db.Backup(w, 0)
// or: shutdown badger, rsync --archive the directory, then open
Defensive patterns

Strategy: try-catch

Validate before calling

// Go: pre-flight checks before opening badger
func checkVlogDir(dir string) error {
    fi, err := os.Stat(dir)
    if err != nil {
        return err
    }
    if !fi.IsDir() {
        return fmt.Errorf("%s is not a directory", dir)
    }
    f, err := os.OpenFile(dir, os.O_RDWR, 0o700)
    if err != nil {
        return err
    }
    return f.Close()
}

Type guard

func isVlogFileError(err error) bool {
    return err != nil && strings.Contains(err.Error(), ". Path=")
}

Try / catch

if err := db.Open(opt); err != nil {
    var perr *os.PathError
    if errors.As(err, &perr) {
        log.Printf("vlog file %s: %v — check perms/fd limits", perr.Path, perr.Err)
    }
    return fmt.Errorf("badger open failed: %w", err)
}

Prevention

When it happens

Trigger: Any failure while opening or iterating a value log file: DB.Open with a corrupted/unreadable *.vlog file, insufficient file descriptors, wrong permissions on the badger directory, a vlog file deleted or truncated while the DB runs, or disk I/O errors during replay.

Common situations: Restoring a badger directory from partial backups; running with ulimit -n too low so os.Open fails; read-only filesystem mounts; copying DB files while badger was running; disk full or hardware errors during vlog replay.

Related errors

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