AlistGo/alist · error

invalid json

Error message

invalid json

What it means

unmarshalMetadata performs a cheap sanity pre-check before json.Unmarshal: the data must be at least 2 bytes and start with '{' and end with '}'. Failing this returns 'invalid json', meaning the metadata content is not a JSON object at all — truncated, empty, or garbage.

Solutions

  1. Inspect the actual metadata file content on the remote storage to see what it really contains
  2. Delete the corrupted chunk set (metadata + chunk files) and re-upload the original file
  3. If an error page was stored, fix the underlying storage driver/auth issue first, then re-upload
Defensive patterns

Strategy: try-catch

Validate before calling

if len(data) < 2 || data[0] != '{' || data[len(data)-1] != '}' {
    return fmt.Errorf("metadata at %s is not a JSON object; got %q", path, truncate(data, 80))
}

Try / catch

meta, err := readMeta(ctx, p)
if err != nil && strings.Contains(err.Error(), "invalid json") {
    log.Printf("corrupt metadata for %s, first bytes: %q", p, head(data))
    // schedule re-upload of the file instead of retrying reads
}

Prevention

When it happens

Trigger: A metadata companion file that is empty, a single byte, or whose first/last bytes are not braces — e.g. an HTML error page saved as the metadata file by a misbehaving remote, a truncated upload, or a plaintext marker written by another program. Raised whenever the chunker reads metadata for a chunked file.

Common situations: Remote storage returning an error page instead of file content; interrupted metadata writes; third-party tools creating similarly-named files that the chunker mistakes for metadata.

Understand the failure class

Related errors


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

Appendix: source

Thrown at drivers/chunker/util.go:223

		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 {
		return nil, errors.New("wrong number of chunks")
	}
	if meta.MD5 != "" {

View on GitHub (pinned to 843d9dc814)