weaviate/weaviate · error

%s: %s > %s

Error message

%s: %s > %s

What it means

checkRestorableVersion refuses to restore a backup whose structure major version exceeds the running server's major version (maxMajorVersion, parsed from the Weaviate build version). Forward-restore is unsupported because the backup format may be newer than the code understands. The message reads 'unable to restore backup as it was produced by a higher version: <backupVersion> > <serverVersion>'.

Source

Thrown at usecases/backup/handler.go:89

}

// maxMajorVersion is the newest backup-structure major version this build restores.
var maxMajorVersion, _ = parseMajor(Version)

// checkRestorableVersion refuses backups this build cannot restore, either because their
// format is too old or because a later Weaviate produced them. version is the
// backup-structure version; serverVersion is the Weaviate version that wrote it.
func checkRestorableVersion(version, serverVersion string) error {
	// An empty version means a corrupt descriptor rather than an old one; Validate reports it.
	if version != "" && version <= version1 {
		return errLegacyUncompressed
	}
	if serverVersionOlderThan(serverVersion, 1, 23) {
		return errLegacyFlatFS
	}
	// A structure version may omit the minor, so compare majors only.
	if major, ok := parseMajor(version); ok && major > maxMajorVersion {
		return fmt.Errorf("%s: %s > %s", errMsgHigherVersion, version, Version)
	}
	return nil
}

// parseMajor reads the leading number of a "major[.minor[.patch]]" version. ok is false
// when it is missing or unparseable.
func parseMajor(version string) (major int, ok bool) {
	major, err := strconv.Atoi(strings.Split(version, ".")[0])
	return major, err == nil
}

// parseVersion splits a "major.minor[.patch]" version. ok is false when either number is
// missing or unparseable.
func parseVersion(version string) (major, minor int, ok bool) {
	parts := strings.Split(version, ".")
	if len(parts) < 2 {
		return 0, 0, false
	}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Upgrade the target Weaviate to a version >= the version that produced the backup (shown in the error).
2. If upgrade is impossible, restore on a cluster running the backup's version (or newer within the same major), then migrate data via client export.
3. Never downgrade a cluster below the version of its most recent backups if restore capability matters.

if major, ok := parseMajor(desc.StructureVersion); ok {
    var cur int
    fmt.Sscanf(Version, "%d", &cur)
    if major > cur {
        return fmt.Errorf("backup from newer Weaviate (%s > %s); upgrade target", desc.StructureVersion, Version)
    }
}

if err := coordinator.Restore(ctx, req); err != nil {
    if strings.Contains(err.Error(), "produced by a higher version") {
        // upgrade the target cluster to the backup's version before retrying
    }
}

When it happens

Trigger: validateRestoreRequest/validate -> checkRestorableVersion finds the descriptor's structure version major greater than the current Weaviate major version — e.g. restoring a backup made on Weaviate v2.x (or a newer major) into a v1.x server, or restoring into a downgraded cluster.

Common situations: Cluster was downgraded after the backup was taken; disaster-recovery site runs an older Weaviate than production; mixing releases across environments.

Related errors

• migrate from pre 1.23: %w
• backup was created %s, and can no longer be restored: restor
• migrate to pre 1.23: %w
• %s: %s > %s
• no roles or users to restore: %w

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/45bd8aad6560e2ba. Report an issue: GitHub.