{"record":{"id":"95a477214194eb63","repo":"AlistGo/alist","slug":"unknown-metadata-version","errorCode":null,"errorMessage":"unknown metadata version","messagePattern":"unknown metadata version","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/chunker/util.go","lineNumber":252,"sourceCode":"\t}\n\tif *meta.Size < 0 {\n\t\treturn nil, errors.New(\"negative file size\")\n\t}\n\tif *meta.ChunkNum < 1 || *meta.ChunkNum > maxSafeChunkNumber {\n\t\treturn nil, errors.New(\"wrong number of chunks\")\n\t}\n\tif meta.MD5 != \"\" {\n\t\tif _, err := hex.DecodeString(meta.MD5); err != nil || len(meta.MD5) != 32 {\n\t\t\treturn nil, errors.New(\"wrong md5 hash\")\n\t\t}\n\t}\n\tif meta.SHA1 != \"\" {\n\t\tif _, err := hex.DecodeString(meta.SHA1); err != nil || len(meta.SHA1) != 40 {\n\t\t\treturn nil, errors.New(\"wrong sha1 hash\")\n\t\t}\n\t}\n\tif *meta.Version > chunkerMetadataVerion {\n\t\treturn nil, errors.New(\"unknown metadata version\")\n\t}\n\treturn &chunkMetadata{\n\t\tVersion: *meta.Version,\n\t\tSize:    *meta.Size,\n\t\tNChunks: *meta.ChunkNum,\n\t\tMD5:     meta.MD5,\n\t\tSHA1:    meta.SHA1,\n\t\tXactID:  meta.XactID,\n\t}, nil\n}\n\nfunc joinRemotePathWithBase(baseMountPath, logicalPath string) string {\n\tlogicalPath = utils.FixAndCleanPath(logicalPath)\n\tif utils.PathEqual(logicalPath, \"/\") {\n\t\treturn utils.FixAndCleanPath(baseMountPath)\n\t}\n\treturn path.Join(utils.FixAndCleanPath(baseMountPath), logicalPath)\n}","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/AlistGo/alist/blob/843d9dc8149126976b2625911e45a4d3ffd6f2f5/drivers/chunker/util.go#L234-L270","documentation":"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.","triggerScenarios":"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.","commonSituations":"Downgrading alist or mixing versions across nodes against the same remote storage; a fork bumping the metadata version; future format migrations.","solutions":["Upgrade alist (or the chunker driver) to a version that supports metadata version in the file","Or re-chunk the files with the current version: download via the new version, then re-upload through the old one","Avoid accessing one chunker target from mixed versions simultaneously during upgrades"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"const supportedMetaVersion = 2 // keep in sync with the driver build you deploy\nvar probe struct{ Ver *int `json:\"ver\"` }\n_ = json.Unmarshal(data, &probe)\nif probe.Ver != nil && *probe.Ver > supportedMetaVersion {\n    return fmt.Errorf(\"metadata ver %d too new for this build; upgrade required\", *probe.Ver)\n}","typeGuard":"func metadataVersionSupported(data []byte, max int) bool {\n    var probe struct{ Ver *int `json:\"ver\"` }\n    return json.Unmarshal(data, &probe) == nil && (probe.Ver == nil || *probe.Ver <= max)\n}","tryCatchPattern":"if err := readChunked(ctx, p); err != nil && strings.Contains(err.Error(), \"unknown metadata version\") {\n    // fallback: route reads through the newer deployment, or re-upload the file\n}","preventionTips":["Upgrade all nodes accessing a shared chunker remote together","During version rollouts, finish migrations before downgrading any binary"],"tags":["chunker","metadata","version","upgrade"],"backgroundTag":null,"analyzedSha":"843d9dc8149126976b2625911e45a4d3ffd6f2f5","analyzedAt":"2026-08-15T12:14:11.722Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}