AlistGo/alist · error

name token must come before chunk token

Error message

name token must come before chunk token

What it means

In the chunker chunk name format, the {name} token must appear before the {chunk} token. The driver compiles the pattern into a printf format (dataNameFmt) and a reverse-matching regexp that both assume name-then-chunk ordering; a pattern with {chunk} first would break reconstruction of the original file name.

Source

Thrown at drivers/chunker/util.go:86

	}
	return paths
}

func (d *Chunker) setChunkNameFormat(pattern string) error {
	if dir, _ := path.Split(pattern); dir != "" {
		return errors.New("directory separator prohibited")
	}

	nameStart, nameEnd, err := parseNameToken(pattern)
	if err != nil {
		return err
	}
	chunkStart, chunkEnd, chunkWidth, err := parseChunkToken(pattern)
	if err != nil {
		return err
	}
	if nameStart > chunkStart {
		return errors.New("name token must come before chunk token")
	}

	reDigits := "[0-9]+"
	if chunkWidth > 0 {
		reDigits = fmt.Sprintf("[0-9]{%d,}", chunkWidth)
	}
	reDataOrCtrl := fmt.Sprintf("(?:(%s)|_(%s))", reDigits, ctrlTypeRegStr)

	beforeName := pattern[:nameStart]
	between := pattern[nameEnd:chunkStart]
	afterChunk := pattern[chunkEnd:]

	strRegex := fmt.Sprintf(
		"^%s(.+?)%s%s%s(?:%s|%s)?$",
		regexp.QuoteMeta(beforeName),
		regexp.QuoteMeta(between),
		reDataOrCtrl,
		regexp.QuoteMeta(afterChunk),

View on GitHub (pinned to 843d9dc814)

Solutions

1. Reorder the pattern so {name} comes first: '{name}_{chunk:03}'
2. If chunk-number-first sorting is desired, use a fixed-width chunk token after the name and sort by it, or rely on listing options instead
3. Validate the pattern in a scratch program or test before saving the storage config

Example fix

// before
chunk_name_format: {chunk:03}_{name}
// after
chunk_name_format: {name}_{chunk:03}

nameIdx := strings.Index(f, "{name}")
chunkIdx := strings.Index(f, "{chunk}")
if nameIdx == -1 || chunkIdx == -1 || nameIdx > chunkIdx {
    return fmt.Errorf("format must contain {name} before {chunk}: %q", f)
}

When it happens

Trigger: Setting chunk_name_format to something like '{chunk:03}_{name}' or 'part-{chunk}-of-{name}' where parseNameToken's start index is greater than parseChunkToken's start index. Fails during setChunkNameFormat at storage init.

Common situations: Users wanting the chunk number first for sorting in listings; templates copied from another tool with different token rules; typos swapping token order.

Related errors

• directory separator prohibited
• pattern must contain one name token: {name}
• pattern must contain exactly one name token: {name}
• pattern must contain one chunk token: {chunk} or {chunk:N}
• pattern must contain exactly one chunk token: {chunk} or {ch

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