hyperledger/fabric · error

fileSuffix [%s] illegal, cannot contain os path separator

Error message

fileSuffix [%s] illegal, cannot contain os path separator

What it means

validateFileSuffix rejects a fileSuffix containing the OS path separator because suffixes are appended to base names; a separator would let the suffix cross directories, which is unsafe and unsupported. New calls this validation and fails fast.

Source

Thrown at orderer/common/filerepo/filerepo.go:172

	return strings.TrimSuffix(baseFile, "."+r.fileSuffix)
}

func (r *Repo) baseToFilePath(baseName string) string {
	return filepath.Join(r.fileRepoDir, r.baseToFileName(baseName))
}

func (r *Repo) baseToFileName(baseName string) string {
	return baseName + "." + r.fileSuffix
}

func validateFileSuffix(fileSuffix string) error {
	if len(fileSuffix) == 0 {
		return errors.New("fileSuffix illegal, cannot be empty")
	}

	if strings.Contains(fileSuffix, string(os.PathSeparator)) {
		return errors.Errorf("fileSuffix [%s] illegal, cannot contain os path separator", fileSuffix)
	}

	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Strip path separators or pass only the bare extension name (e.g. "block", not "dir/block")
2. If a directory component is needed, change the directory passed to New instead of the suffix
3. Sanitize config input with strings.ReplaceAll(value, string(os.PathSeparator), "") before calling New

Example fix

// before
repo, err := filerepo.New(dir, filepath.Join("snapshots", "snap"))
// after
repo, err := filerepo.New(filepath.Join(dir, "snapshots"), "snap")

func validateRepoParams(dir, suffix string) error {
    if strings.Contains(suffix, string(os.PathSeparator)) {
        return errors.New("fileSuffix must not contain path separators")
    }
    if strings.ContainsAny(suffix, `\/`) {
        return errors.New("fileSuffix must not contain slashes")
    }
    return nil
}

func isSafeSuffix(s string) bool {
    return len(s) > 0 && !strings.Contains(s, string(os.PathSeparator)) && !strings.Contains(s, "/")
}

repo, err := filerepo.New(dir, suffix)
if err != nil && strings.Contains(err.Error(), "cannot contain os path separator") {
    return fmt.Errorf("bad fileSuffix %q: use a bare extension name", suffix)
}

When it happens

Trigger: Calling New with a fileSuffix such as "a/b", "block/", or a value containing os.PathSeparator (Linux '/' or Windows '\\').

Common situations: User-supplied configuration where a full path was pasted into a suffix field; building the suffix with filepath.Join instead of a plain string; cross-platform defaults containing backslashes.

Related errors

• cannot collect files from empty chaincode path
• plugin with name %s wasn't found
• number of retries must be zero or greater
• fileSuffix illegal, cannot be empty
• chaincode type not supported: %s

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/37afffb0af8426fd. Report an issue: GitHub.