thanos-io/thanos · error

unexpected meta file version

Error message

unexpected meta file version %d

What it means

ReadMetaFile validates that the parsed Meta.Version equals MetaVersion1. If the meta file was written with a different (newer or unsupported) version, this error is thrown, refusing to interpret data whose layout it does not understand.

Solutions

1. Check the `version` field in the meta file and restore it to 1 if it was accidentally edited.
2. Upgrade (or match) the Thanos/shipper version to the one that wrote the meta file.
3. Regenerate the meta file via a fresh shipper Sync if the data can be re-derived.
4. Restore the file from backup or the object store copy if it was corrupted.

Example fix

// before (meta.json)
{"version": 2, ...}
// after
{"version": 1, ...}

b, _ := os.ReadFile(path)
var probe struct{ Version int `json:"version"` }
if json.Unmarshal(b, &probe) == nil && probe.Version != 1 {
    return fmt.Errorf("unsupported meta version %d at %s", probe.Version, path)
}

if _, err := shipper.ReadMetaFile(path); err != nil {
    if strings.Contains(err.Error(), "unexpected meta file version") {
        // handle version mismatch: upgrade binary or restore file
    }
}

When it happens

Trigger: Calling ReadMetaFile/Sync/UploadedBlocks/AreAllBlocksUploaded on a meta.json whose `version` field is not 1 — e.g. a file produced by a newer Thanos release or hand-edited to a different value.

Common situations: Upgraded binaries vs. data written by a different version; experimental forks bumping MetaVersion; manual edits of meta.json setting an arbitrary version; mixing storage from different Thanos versions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unexpected meta file
• not supported index file version
• unexpected no-compact-mark file version
• unexpected no-downsample-mark file version
• unexpected deletion-mark file version

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/1762c12ba8d021a3. Report an issue: GitHub.

Appendix: source

Thrown at pkg/shipper/shipper.go:661

	if err := f.Close(); err != nil {
		return err
	}
	return renameFile(logger, tmp, path)
}

// ReadMetaFile reads the given meta from <dir>/thanos.shipper.json.
func ReadMetaFile(path string) (*Meta, error) {
	b, err := os.ReadFile(path)
	if err != nil {
		return nil, errors.Wrapf(err, "failed to read %s", path)
	}

	var m Meta
	if err := json.Unmarshal(b, &m); err != nil {
		return nil, errors.Wrapf(err, "failed to parse %s as JSON: %q", path, string(b))
	}
	if m.Version != MetaVersion1 {
		return nil, errors.Errorf("unexpected meta file version %d", m.Version)
	}

	return &m, nil
}

func renameFile(logger log.Logger, from, to string) error {
	if err := os.RemoveAll(to); err != nil {
		return err
	}
	if err := os.Rename(from, to); err != nil {
		return err
	}

	// Directory was renamed; sync parent dir to persist rename.
	pdir, err := fileutil.OpenDir(filepath.Dir(to))
	if err != nil {
		return err
	}

View on GitHub (pinned to 35b8b99117)