benbjohnson/litestream · warning

parse hydration meta: %w

Error message

parse hydration meta: %w

What it means

Hydrator.loadMeta parses the .meta sidecar file that stores the last hydrated TXID and wraps strconv.ParseUint failures as "parse hydration meta". The meta file must contain a single decimal TXID; any other content makes resuming hydration impossible.

Source

Thrown at vfs.go:976

	}
	if err := os.Remove(h.metaPath()); err != nil && !os.IsNotExist(err) {
		return err
	}
	return nil
}

func (h *Hydrator) metaPath() string {
	return h.path + ".meta"
}

func (h *Hydrator) loadMeta() (ltx.TXID, error) {
	data, err := os.ReadFile(h.metaPath())
	if err != nil {
		return 0, err
	}
	v, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 64)
	if err != nil {
		return 0, fmt.Errorf("parse hydration meta: %w", err)
	}
	return ltx.TXID(v), nil
}

func (h *Hydrator) saveMeta() error {
	h.mu.Lock()
	txid := h.txid
	h.mu.Unlock()

	dir := filepath.Dir(h.metaPath())
	tmp, err := os.CreateTemp(dir, ".hydration-meta-*")
	if err != nil {
		return fmt.Errorf("create temp meta file: %w", err)
	}
	tmpPath := tmp.Name()

	if _, err := fmt.Fprintf(tmp, "%d\n", txid); err != nil {
		if closeErr := tmp.Close(); closeErr != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Inspect the .meta file next to the hydration file; delete it if it is empty or corrupt — litestream will fall back to a full re-hydration
2. Use litestream reset for the database to clear hydration state cleanly
3. Ensure all litestream instances use the same version so the meta format matches
4. Avoid manually editing generated .meta files

Example fix

// before: hard failure on corrupt meta
v, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 64)
if err != nil {
	return 0, fmt.Errorf("parse hydration meta: %w", err)
}
// after: caller treats corrupt meta as 'no saved state'
txid, err := h.loadMeta()
if err != nil {
	txid = 0 // re-hydrate from scratch
}

// validate meta before litestream reads it
if data, err := os.ReadFile(hydrationPath + ".meta"); err == nil {
	if _, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 64); err != nil {
		os.Remove(hydrationPath + ".meta") // force clean re-hydration
	}
}

When it happens

Trigger: The <hydration-path>.meta file exists but contains corrupt/non-numeric content — e.g. an empty file from a crashed previous write, binary garbage, or manual edits; a version change altered the meta format.

Common situations: Power loss or kill -9 mid-write on older versions that wrote the meta non-atomically; leftover meta files from a different litestream version; someone opening the file in an editor and saving garbage.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• create hydration directory: %w
• open persistent hydration file: %w
• remove stale hydration meta: %w
• create hydration file: %w
• write hydration meta: %w

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