AlistGo/alist · error

metadata can't be this big

Error message

metadata can't be this big

What it means

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.

Source

Thrown at drivers/chunker/util.go:213

	return dir + match[1], chunkNo, match[3], xactID
}

func marshalMetadata(size int64, nChunks int, md5Value, sha1Value, xactID string) ([]byte, error) {
	version := chunkerMetadataVerion
	if xactID == "" && version == 2 {
		version = 1
	}
	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")
	}

View on GitHub (pinned to 843d9dc814)

Solutions

1. 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
2. On stock builds, report a bug — stock metadata cannot normally reach 255 bytes
3. Check that size/nchunks values are sane (not corrupted huge numbers) before upload

meta := buildMetadata(...) // your struct
data, err := json.Marshal(meta)
if err == nil && len(data) >= 255 {
    return fmt.Errorf("metadata too large (%d bytes) before upload", len(data))
}

tryErr := drv.Put(ctx, ...)
if tryErr != nil && strings.Contains(tryErr.Error(), "metadata can't be this big") {
    // strip optional hash fields / re-chunk with larger chunk size and retry once
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• wrong number of chunks
• metadata is too large
• invalid json
• missing required field
• wrong version

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