AlistGo/alist · error

chunk width in {chunk:N} must be a positive integer

Error message

chunk width in {chunk:N} must be a positive integer

What it means

The width N inside a {chunk:N} token failed strconv.Atoi or parsed to a value <= 0. The width sets the minimum zero-padding of chunk numbers in generated names (and the regex '[0-9]{N,}' used to find chunks), so it must be a positive decimal integer.

Source

Thrown at drivers/chunker/util.go:150

	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)
	name := fmt.Sprintf(d.dataNameFmt, baseName, chunkNo+d.StartFrom)
	if xactID != "" {
		name += fmt.Sprintf(tempSuffixFormat, xactID)
	}
	return dir + name
}

func (d *Chunker) parseChunkName(filePath string) (parentPath string, chunkNo int, ctrlType, xactID string) {
	dir, name := path.Split(filePath)
	match := d.nameRegexp.FindStringSubmatch(name)
	if match == nil || match[1] == "" {

View on GitHub (pinned to 843d9dc814)

Solutions

1. Use a positive width such as {chunk:03}, {chunk:05}
2. For no padding at all, use the plain {chunk} token instead of {chunk:0}
3. Keep widths modest (2–6 digits) so file names stay short and under the 255-byte metadata/name limits

Example fix

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

var widthRe = regexp.MustCompile(`^\{chunk:([0-9]+)\}$`)
if m := widthRe.FindStringSubmatch(token); m != nil {
    w, _ := strconv.Atoi(m[1])
    if w <= 0 {
        return fmt.Errorf("chunk width must be positive, got %d", w)
    }
}

When it happens

Trigger: chunk_name_format containing '{chunk:0}', '{chunk:-3}', '{chunk:abc}', or a huge number that overflows Atoi. Note the regexp only captures digits, so in practice this fires for '{chunk:0}' or an all-digit string that overflows int. Fails at init in parseChunkToken.

Common situations: Using 0 padding width by habit; negative widths copied from other tools; very large widths (e.g. 99999999999999999999) causing Atoi range errors.

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 one chunk token: {chunk} or {chunk:N}

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