AlistGo/alist · error

missing required field

Error message

missing required field

What it means

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.

Source

Thrown at drivers/chunker/util.go:230

	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 {
		return nil, errors.New("wrong number of chunks")
	}
	if meta.MD5 != "" {
		if _, err := hex.DecodeString(meta.MD5); err != nil || len(meta.MD5) != 32 {
			return nil, errors.New("wrong md5 hash")
		}
	}
	if meta.SHA1 != "" {
		if _, err := hex.DecodeString(meta.SHA1); err != nil || len(meta.SHA1) != 40 {
			return nil, errors.New("wrong sha1 hash")

View on GitHub (pinned to 843d9dc814)

Solutions

1. Regenerate the metadata by deleting the chunked file set and re-uploading the file through the chunker mount
2. If interoperability with an older format matters, patch metadataJSON handling to default missing fields instead of failing — upstream treats them as mandatory
3. Do not hand-write metadata files; always upload through the driver

// Pre-check the raw JSON keys before handing data to the driver
var probe map[string]json.RawMessage
_ = json.Unmarshal(data, &probe)
for _, k := range []string{"ver", "size", "nchunks"} {
    if _, ok := probe[k]; !ok {
        return fmt.Errorf("metadata missing required key %q", k)
    }
}

func hasRequiredMetaKeys(data []byte) bool {
    var probe map[string]json.RawMessage
    return json.Unmarshal(data, &probe) == nil && probe["ver"] != nil && probe["size"] != nil && probe["nchunks"] != nil
}

When it happens

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

Common situations: Metadata written by an incompatible chunker version that omitted a field; manual crafting of metadata; merging/migrating remotes with tools that strip JSON fields.

Related errors

• wrong version
• negative file size
• remote_path is required
• chunk_size must be positive
• directory separator prohibited

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