{"record":{"id":"2abe3b0faa71de99","repo":"AlistGo/alist","slug":"missing-required-field","errorCode":null,"errorMessage":"missing required field","messagePattern":"missing required field","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/chunker/util.go","lineNumber":230,"sourceCode":"\tif err == nil && len(data) >= maxMetadataSizeWrite {\n\t\treturn nil, errors.New(\"metadata can't be this big\")\n\t}\n\treturn data, err\n}\n\nfunc unmarshalMetadata(data []byte) (*chunkMetadata, error) {\n\tif len(data) > maxMetadataSizeWrite {\n\t\treturn nil, errors.New(\"metadata is too large\")\n\t}\n\tif data == nil || len(data) < 2 || data[0] != '{' || data[len(data)-1] != '}' {\n\t\treturn nil, errors.New(\"invalid json\")\n\t}\n\tvar meta metadataJSON\n\tif err := json.Unmarshal(data, &meta); err != nil {\n\t\treturn nil, err\n\t}\n\tif meta.Version == nil || meta.Size == nil || meta.ChunkNum == nil {\n\t\treturn nil, errors.New(\"missing required field\")\n\t}\n\tif *meta.Version < 1 {\n\t\treturn nil, errors.New(\"wrong version\")\n\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\")","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/AlistGo/alist/blob/843d9dc8149126976b2625911e45a4d3ffd6f2f5/drivers/chunker/util.go#L212-L248","documentation":"After successfully JSON-decoding metadata, the driver requires the pointer fields ver, size, and nchunks to be present. metadataJSON declares them as *int/*int64, so a JSON object missing any of those keys decodes to nil pointers, and this error is returned: the metadata is structurally incomplete.","triggerScenarios":"A metadata file like '{\"ver\":1,\"size\":123}' (missing nchunks) or '{}' — any valid JSON object lacking one of the three required keys. Happens when reading a chunked file whose companion metadata was written by an older version, a fork, or by hand.","commonSituations":"Metadata written by an incompatible chunker version that omitted a field; manual crafting of metadata; merging/migrating remotes with tools that strip JSON fields.","solutions":["Regenerate the metadata by deleting the chunked file set and re-uploading the file through the chunker mount","If interoperability with an older format matters, patch metadataJSON handling to default missing fields instead of failing — upstream treats them as mandatory","Do not hand-write metadata files; always upload through the driver"],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"// Pre-check the raw JSON keys before handing data to the driver\nvar probe map[string]json.RawMessage\n_ = json.Unmarshal(data, &probe)\nfor _, k := range []string{\"ver\", \"size\", \"nchunks\"} {\n    if _, ok := probe[k]; !ok {\n        return fmt.Errorf(\"metadata missing required key %q\", k)\n    }\n}","typeGuard":"func hasRequiredMetaKeys(data []byte) bool {\n    var probe map[string]json.RawMessage\n    return json.Unmarshal(data, &probe) == nil && probe[\"ver\"] != nil && probe[\"size\"] != nil && probe[\"nchunks\"] != nil\n}","tryCatchPattern":null,"preventionTips":["Only produce metadata through the chunker driver itself","When migrating remotes, validate metadata documents contain ver/size/nchunks"],"tags":["chunker","metadata","schema","validation"],"backgroundTag":null,"analyzedSha":"843d9dc8149126976b2625911e45a4d3ffd6f2f5","analyzedAt":"2026-08-15T12:14:11.722Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}