AlistGo/alist · error
metadata is too large
Error message
metadata is too large
What it means
unmarshalMetadata rejects any metadata companion file whose content length exceeds maxMetadataSizeWrite (255 bytes). This is a read-side guard symmetric to the write-side 'metadata can't be this big' check: metadata larger than the cap was never produced by this driver, so it is treated as invalid/corrupt rather than parsed.
Source
Thrown at drivers/chunker/util.go:220
}
meta := metadataJSON{
Version: &version,
Size: &size,
ChunkNum: &nChunks,
MD5: md5Value,
SHA1: sha1Value,
XactID: xactID,
}
data, err := json.Marshal(&meta)
if err == nil && len(data) >= maxMetadataSizeWrite {
return nil, errors.New("metadata can't be this big")
}
return data, err
}
func unmarshalMetadata(data []byte) (*chunkMetadata, error) {
if len(data) > maxMetadataSizeWrite {
return nil, errors.New("metadata is too large")
}
if data == nil || len(data) < 2 || data[0] != '{' || data[len(data)-1] != '}' {
return nil, errors.New("invalid json")
}
var meta metadataJSON
if err := json.Unmarshal(data, &meta); err != nil {
return nil, err
}
if meta.Version == nil || meta.Size == nil || meta.ChunkNum == nil {
return nil, errors.New("missing required field")
}
if *meta.Version < 1 {
return nil, errors.New("wrong version")
}
if *meta.Size < 0 {
return nil, errors.New("negative file size")
}
if *meta.ChunkNum < 1 || *meta.ChunkNum > maxSafeChunkNumber {View on GitHub (pinned to 843d9dc814)
Solutions
- Restore or regenerate the metadata file — delete the chunked file set and re-upload the original file so the driver writes fresh metadata
- If the file was chunked by another tool, re-chunk it with this driver's format
- Avoid editing hidden companion files on the chunker's target storage
Defensive patterns
Strategy: try-catch
Validate before calling
obj, err := fs.Get(ctx, metaPath)
if err == nil && obj.GetSize() > 255 {
return fmt.Errorf("metadata object %s is %d bytes (max 255); regenerate it", metaPath, obj.GetSize())
} Try / catch
if err := chunkerRead(ctx, path); err != nil {
if strings.Contains(err.Error(), "metadata is too large") {
// treat as corrupt: quarantine file set, trigger re-upload workflow
}
} Prevention
- Never edit hidden companion metadata files on the target storage
- Monitor chunker remotes for foreign/oversized metadata objects
When it happens
Trigger: Reading a chunked file whose hidden metadata file (e.g. 'file.ext..chunkxx__meta' style companion) is > 255 bytes — caused by manual editing of the metadata file, a different tool writing it, or corruption. Thrown during chunked file open/listing when the metadata object is fetched.
Common situations: Users hand-editing metadata JSON on the remote; files chunked by an incompatible/older fork; metadata file concatenated with other content by a sync tool.
Related errors
AI-assisted analysis of AlistGo/alist@843d9dc814 (2026-08-15).
Data as JSON: /api/errors/26eeaef10e13ff5c.
Report an issue: GitHub.