What causes "fileSuffix illegal, cannot be empty" in hyperledger/fabric?

Pass a non-empty fileSuffix to New (e.g. "block" or "snapshot")

fileSuffix illegal, cannot be empty

Error message

fileSuffix illegal, cannot be empty

What it means

validateFileSuffix rejects an empty fileSuffix because Repo builds file names as baseName + "." + fileSuffix; an empty suffix would create ambiguous names. New calls this validation and fails fast before touching the filesystem.

Source

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

// FileToBaseName strips the suffix from the file name to get the associated channel name.
func (r *Repo) FileToBaseName(fileName string) string {
	baseFile := filepath.Base(fileName)

	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

Pass a non-empty fileSuffix to New (e.g. "block" or "snapshot")
If loaded from configuration, set the corresponding config value or default it in code
Add a startup-time config check so empty suffixes are rejected with a clearer message

Example fix

// before
repo, err := filerepo.New(dir, "")
// after
repo, err := filerepo.New(dir, "block")

Defensive patterns

Strategy: validation

Validate before calling

func validateRepoParams(dir, suffix string) error {
    if suffix == "" {
        return errors.New("fileSuffix must be non-empty")
    }
    return nil
}
// call before filerepo.New(dir, suffix)

Type guard

func hasSuffix(suffix string) bool { return len(suffix) > 0 }

Try / catch

repo, err := filerepo.New(dir, suffix)
if err != nil && err.Error() == "fileSuffix illegal, cannot be empty" {
    return fmt.Errorf("configuration error: fileSuffix must be set, got %q", suffix)
}

Prevention

Default the suffix in code rather than reading raw config
Fail config loading early when required string fields are empty
Keep suffixes as constants, not free-form user input

When it happens

Trigger: Calling New (directly or via a higher-level constructor such as a block repository initializer) with fileSuffix = "" in the options/arguments.

Common situations: Programmatic construction of a Repo or BlockRepository where the suffix is read from config and the config key is unset or bound to an empty string; accidental clearing of a constant in refactoring.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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