{"record":{"id":"4e349918f47909a9","repo":"AlistGo/alist","slug":"metadata-can-t-be-this-big","errorCode":null,"errorMessage":"metadata can't be this big","messagePattern":"metadata can't be this big","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"drivers/chunker/util.go","lineNumber":213,"sourceCode":"\treturn dir + match[1], chunkNo, match[3], xactID\n}\n\nfunc marshalMetadata(size int64, nChunks int, md5Value, sha1Value, xactID string) ([]byte, error) {\n\tversion := chunkerMetadataVerion\n\tif xactID == \"\" && version == 2 {\n\t\tversion = 1\n\t}\n\tmeta := metadataJSON{\n\t\tVersion:  &version,\n\t\tSize:     &size,\n\t\tChunkNum: &nChunks,\n\t\tMD5:      md5Value,\n\t\tSHA1:     sha1Value,\n\t\tXactID:   xactID,\n\t}\n\tdata, err := json.Marshal(&meta)\n\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}","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/AlistGo/alist/blob/843d9dc8149126976b2625911e45a4d3ffd6f2f5/drivers/chunker/util.go#L195-L231","documentation":"marshalMetadata refuses to serialize chunk metadata when the JSON encoding of the metadata struct (version, size, nchunks, md5, sha1, txn) reaches or exceeds maxMetadataSizeWrite (255 bytes). The metadata is stored as the content of a hidden companion file on the remote, and name/content constraints of the underlying storage demand this cap.","triggerScenarios":"Uploading a file whose metadata JSON serializes to >= 255 bytes — the fixed fields are small, so this is only reachable with abnormally large values (e.g. a Size or ChunkNum rendered with many digits) or if metadata fields grow in a fork; the check is len(data) >= maxMetadataSizeWrite after json.Marshal succeeds.","commonSituations":"Custom forks that add fields to metadataJSON; extremely large files producing very long integer fields; rarely hit on stock builds since stock JSON stays well under 255 bytes.","solutions":["If you forked the driver and added metadata fields, trim optional fields (omit md5/sha1/txn when empty) or raise maxMetadataSizeWrite deliberately and verify the backend accepts the larger companion file","On stock builds, report a bug — stock metadata cannot normally reach 255 bytes","Check that size/nchunks values are sane (not corrupted huge numbers) before upload"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"meta := buildMetadata(...) // your struct\ndata, err := json.Marshal(meta)\nif err == nil && len(data) >= 255 {\n    return fmt.Errorf(\"metadata too large (%d bytes) before upload\", len(data))\n}","typeGuard":null,"tryCatchPattern":"tryErr := drv.Put(ctx, ...)\nif tryErr != nil && strings.Contains(tryErr.Error(), \"metadata can't be this big\") {\n    // strip optional hash fields / re-chunk with larger chunk size and retry once\n}","preventionTips":["If extending metadataJSON in a fork, run marshal tests asserting len < 255","Omit md5/sha1/txn when empty to keep the JSON small"],"tags":["chunker","metadata","limits","upload"],"backgroundTag":null,"analyzedSha":"843d9dc8149126976b2625911e45a4d3ffd6f2f5","analyzedAt":"2026-08-15T12:14:11.722Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}