AlistGo/alist · error

directory separator prohibited

Error message

directory separator prohibited

What it means

The Chunker driver's chunk name format option (setChunkNameFormat) rejects any pattern containing a directory separator ('/' on the path side of path.Split). Chunk file names are flat: the driver derives the directory from the original file path and only the base name is templated, so '/' in the pattern is ambiguous and forbidden.

Source

Thrown at drivers/chunker/util.go:74

		}
		p = utils.FixAndCleanPath(p)
		if _, ok := seen[p]; ok {
			return
		}
		seen[p] = struct{}{}
		paths = append(paths, p)
	}

	addPath(d.RemotePath)
	for _, line := range strings.Split(d.RemotePaths, "\n") {
		addPath(line)
	}
	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)
	}

View on GitHub (pinned to 843d9dc814)

Solutions

1. Remove all '/' characters from chunk_name_format, e.g. use '{name}_{chunk:03}' instead of '{name}/{chunk:03}'
2. Keep any folder structure on the mount/remote path configuration, not in the chunk name pattern
3. If nested chunk dirs are a hard requirement, file a feature request — the format language intentionally cannot express it

Example fix

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

// Validate before saving the chunker storage config
if strings.Contains(chunkNameFormat, "/") || strings.Contains(chunkNameFormat, "\\") {
    return fmt.Errorf("chunk name format must not contain directory separators: %q", chunkNameFormat)
}

When it happens

Trigger: Configuring the chunker storage with a chunk_name_format like '{name}/part-{chunk}' or any pattern where path.Split returns a non-empty dir portion. Raised immediately at driver Init/config validation, before any upload.

Common situations: Users migrating from other chunking tools that put chunks in subdirectories; copy-pasting a template that includes a path prefix; expecting 'dir/{name}_{chunk}' to create nested folders.

Related errors

• 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}
• 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/9bdd2ba9ec97f991. Report an issue: GitHub.