benbjohnson/litestream · error

decode database: %w

Error message

decode database: %w

What it means

The LTX decoder failed while writing the compacted database image to the temp file. Either a streamed LTX file was corrupt/truncated (checksum or framing error from the compactor goroutine) or the local disk write failed.

Source

Thrown at replica.go:752

		return fmt.Errorf("create temp database path: %w", err)
	}
	defer func() { _ = f.Close() }()

	pr, pw := io.Pipe()

	go func() {
		c, err := ltx.NewCompactor(pw, rdrs)
		if err != nil {
			pw.CloseWithError(fmt.Errorf("new ltx compactor: %w", err))
			return
		}
		c.HeaderFlags = ltx.HeaderFlagNoChecksum
		_ = pw.CloseWithError(c.Compact(ctx))
	}()

	dec := ltx.NewDecoder(pr)
	if err := dec.DecodeDatabaseTo(f); err != nil {
		return fmt.Errorf("decode database: %w", err)
	}

	if err := f.Sync(); err != nil {
		return err
	} else if err := f.Close(); err != nil {
		return err
	}

	// Copy file to final location.
	r.Logger().Debug("renaming database from temporary location")
	if err := os.Rename(tmpOutputPath, opt.OutputPath); err != nil {
		return err
	}
	if err := internal.FsyncDir(filepath.Dir(opt.OutputPath)); err != nil {
		return fmt.Errorf("sync restore output dir: %w", err)
	}

	if opt.IntegrityCheck != IntegrityCheckNone {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check disk space and permissions at the output location
2. Inspect the wrapped error: checksum errors indicate replica-side corruption; retry after removing the bad LTX file

When it happens

Trigger: Thrown at replica.go:752 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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