benbjohnson/litestream · error

write initial txid file: %w

Error message

write initial txid file: %w

What it means

Before entering follow mode, WriteTXIDFile failed to record the initial max TXID to the <db>-txid sidecar. Without it, a restart cannot resume following; causes are permission or disk errors at the output path.

Source

Thrown at replica.go:793

				_ = os.Remove(opt.OutputPath + "-wal")
			}
			return fmt.Errorf("post-restore integrity check: %w", err)
		}
		r.Logger().Info("post-restore integrity check passed")
	}

	// Enter follow mode if enabled, continuously applying new LTX files.
	if opt.Follow {
		for _, rd := range rdrs {
			if closer, ok := rd.(io.Closer); ok {
				_ = closer.Close()
			}
		}
		rdrs = nil

		maxTXID := infos[len(infos)-1].MaxTXID
		if err := WriteTXIDFile(opt.OutputPath, maxTXID); err != nil {
			return fmt.Errorf("write initial txid file: %w", err)
		}
		return r.follow(ctx, opt.OutputPath, maxTXID, opt.FollowInterval)
	}

	return nil
}

// follow enters a continuous restore loop, polling for new LTX files and
// applying them to the restored database. It blocks until the context is
// cancelled (e.g. Ctrl+C). Returns nil on clean shutdown.
func (r *Replica) follow(ctx context.Context, outputPath string, lastTXID ltx.TXID, interval time.Duration) error {
	f, err := os.OpenFile(outputPath, os.O_RDWR, 0)
	if err != nil {
		return fmt.Errorf("open database for follow: %w", err)
	}
	defer func() {
		_ = f.Sync()
		_ = f.Close()

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Check write permissions and disk space at the output location
2. Retry the restore with -follow

When it happens

Trigger: Thrown at replica.go:793 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/a7250a4069c2d2a5. Report an issue: GitHub.