AlistGo/alist · error

unknown metadata version

Error message

unknown metadata version

What it means

The metadata's ver field exceeds chunkerMetadataVersion (currently 2), meaning it was written by a NEWER version of the chunker format than this binary understands. The driver refuses to interpret an unknown format rather than mis-read chunk layout or fields.

Source

Thrown at drivers/chunker/util.go:252

	}
	if *meta.Size < 0 {
		return nil, errors.New("negative file size")
	}
	if *meta.ChunkNum < 1 || *meta.ChunkNum > maxSafeChunkNumber {
		return nil, errors.New("wrong number of chunks")
	}
	if meta.MD5 != "" {
		if _, err := hex.DecodeString(meta.MD5); err != nil || len(meta.MD5) != 32 {
			return nil, errors.New("wrong md5 hash")
		}
	}
	if meta.SHA1 != "" {
		if _, err := hex.DecodeString(meta.SHA1); err != nil || len(meta.SHA1) != 40 {
			return nil, errors.New("wrong sha1 hash")
		}
	}
	if *meta.Version > chunkerMetadataVerion {
		return nil, errors.New("unknown metadata version")
	}
	return &chunkMetadata{
		Version: *meta.Version,
		Size:    *meta.Size,
		NChunks: *meta.ChunkNum,
		MD5:     meta.MD5,
		SHA1:    meta.SHA1,
		XactID:  meta.XactID,
	}, nil
}

func joinRemotePathWithBase(baseMountPath, logicalPath string) string {
	logicalPath = utils.FixAndCleanPath(logicalPath)
	if utils.PathEqual(logicalPath, "/") {
		return utils.FixAndCleanPath(baseMountPath)
	}
	return path.Join(utils.FixAndCleanPath(baseMountPath), logicalPath)
}

View on GitHub (pinned to 843d9dc814)

Solutions

1. Upgrade alist (or the chunker driver) to a version that supports metadata version in the file
2. Or re-chunk the files with the current version: download via the new version, then re-upload through the old one
3. Avoid accessing one chunker target from mixed versions simultaneously during upgrades

const supportedMetaVersion = 2 // keep in sync with the driver build you deploy
var probe struct{ Ver *int `json:"ver"` }
_ = json.Unmarshal(data, &probe)
if probe.Ver != nil && *probe.Ver > supportedMetaVersion {
    return fmt.Errorf("metadata ver %d too new for this build; upgrade required", *probe.Ver)
}

func metadataVersionSupported(data []byte, max int) bool {
    var probe struct{ Ver *int `json:"ver"` }
    return json.Unmarshal(data, &probe) == nil && (probe.Ver == nil || *probe.Ver <= max)
}

if err := readChunked(ctx, p); err != nil && strings.Contains(err.Error(), "unknown metadata version") {
    // fallback: route reads through the newer deployment, or re-upload the file
}

When it happens

Trigger: Reading chunked files whose metadata has "ver":3+, e.g. after the remote was written by an upgraded/newer alist build and then accessed by an older one. Thrown during unmarshalMetadata on file open/list.

Common situations: Downgrading alist or mixing versions across nodes against the same remote storage; a fork bumping the metadata version; future format migrations.

Related errors

• wrong version
• metadata can't be this big
• metadata is too large
• invalid json
• missing required field

AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15). Data as JSON: /api/errors/95a477214194eb63. Report an issue: GitHub.