AlistGo/alist · error

pattern must contain one chunk token: {chunk} or {chunk:N}

Error message

pattern must contain one chunk token: {chunk} or {chunk:N}

What it means

parseChunkToken reports this when the chunk name format contains zero chunk tokens. At least one {chunk} or {chunk:N} token is mandatory so each chunk file gets a unique, sortable number embedded in its name.

Source

Thrown at drivers/chunker/util.go:139

func parseNameToken(pattern string) (start, end int, err error) {
	nameMagicCount := strings.Count(pattern, "{name}")
	switch nameMagicCount {
	case 0:
		return 0, 0, errors.New("pattern must contain one name token: {name}")
	case 1:
	default:
		return 0, 0, errors.New("pattern must contain exactly one name token: {name}")
	}
	start = strings.Index(pattern, "{name}")
	return start, start + len("{name}"), nil
}

func parseChunkToken(pattern string) (start, end, width int, err error) {
	chunkMatches := chunkTokenRegexp.FindAllStringSubmatchIndex(pattern, -1)
	switch len(chunkMatches) {
	case 0:
		return 0, 0, 0, errors.New("pattern must contain one chunk token: {chunk} or {chunk:N}")
	case 1:
	default:
		return 0, 0, 0, errors.New("pattern must contain exactly one chunk token: {chunk} or {chunk:N}")
	}
	match := chunkMatches[0]
	start = match[0]
	end = match[1]
	if match[2] >= 0 && match[3] >= 0 {
		width, err = strconv.Atoi(pattern[match[2]:match[3]])
		if err != nil || width <= 0 {
			return 0, 0, 0, errors.New("chunk width in {chunk:N} must be a positive integer")
		}
	}
	return start, end, width, nil
}

func (d *Chunker) makeChunkName(filePath string, chunkNo int, xactID string) string {
	dir, baseName := path.Split(filePath)

View on GitHub (pinned to 843d9dc814)

Solutions

1. Add a chunk token: '{name}_{chunk}' for unpadded or '{name}_{chunk:03}' for zero-padded numbers
2. Verify the exact spelling — '{Chunk}', '{chunks}', or '{chunk:}' are not matched by chunkTokenRegexp (\\{chunk(:[0-9]+)?\\})

Example fix

// before
chunk_name_format: {name}.part
// after
chunk_name_format: {name}.part_{chunk:03}

var chunkToken = regexp.MustCompile(`\{chunk(:[0-9]+)?\}`)
if len(chunkToken.FindAllString(f, -1)) != 1 {
    return fmt.Errorf("chunk name format must contain exactly one {chunk} or {chunk:N} token: %q", f)
}

When it happens

Trigger: chunk_name_format set to '{name}.part' or just '{name}' — a pattern with {name} but no {chunk}/{chunk:N}. Fails in setChunkNameFormat during storage Init.

Common situations: Users who only want a suffix marker per chunk; forgetting the token after customizing the template; patterns built for a non-chunking driver reused here.

Related errors

• directory separator prohibited
• name token must come before chunk token
• pattern must contain one name token: {name}
• pattern must contain exactly one name token: {name}
• 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/e7e8011eb71abe6a. Report an issue: GitHub.