hyperledger/fabric · error

config ID '%s' contains illegal characters

Error message

config ID '%s' contains illegal characters

What it means

validateConfigID permits only characters matching configAllowedChars in identifiers. If the whole string does not match the allowed-character pattern (checked by comparing the regex match length to the string length), it is rejected. This keeps config IDs restricted to safe name characters.

Source

Thrown at common/configtx/validator.go:64

//  2. Are shorter than 250 characters.
//  3. Are not the strings "." or "..".
func validateConfigID(configID string) error {
	re, _ := regexp.Compile(configAllowedChars)
	// Length
	if len(configID) <= 0 {
		return errors.New("config ID illegal, cannot be empty")
	}
	if len(configID) > MaxLength {
		return errors.Errorf("config ID illegal, cannot be longer than %d", MaxLength)
	}
	// Illegal name
	if _, ok := illegalNames[configID]; ok {
		return errors.Errorf("name '%s' for config ID is not allowed", configID)
	}
	// Illegal characters
	matched := re.FindString(configID)
	if len(matched) != len(configID) {
		return errors.Errorf("config ID '%s' contains illegal characters", configID)
	}

	return nil
}

// ValidateChannelID makes sure that proposed channel IDs comply with the
// following restrictions:
//  1. Contain only lower case ASCII alphanumerics, dots '.', and dashes '-'
//  2. Are shorter than 250 characters.
//  3. Start with a letter
//
// This is the intersection of the Kafka restrictions and CouchDB restrictions
// with the following exception: '.' is converted to '_' in the CouchDB naming
// This is to accommodate existing channel names with '.', especially in the
// behave tests which rely on the dot notation for their sluggification.
//
// note: this function is a copy of the same in core/tx/endorser/parser.go
func ValidateChannelID(channelID string) error {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Remove or replace illegal characters with allowed ones (letters, digits, dot, dash) in the config ID
2. Trim whitespace from all names before adding them to config
3. Add a regex pre-check in tooling that generates config keys
4. Normalize external names (e.g. MSP IDs) into the allowed character set at import time

Example fix

// before
id := fmt.Sprintf("%s peer", orgName) // contains a space
// after
id := strings.ReplaceAll(strings.TrimSpace(orgName), " ", "-") + "-peer"

var allowed = regexp.MustCompile(`^[a-zA-Z0-9.-]+$`)
if !allowed.MatchString(configID) {
    return errors.Errorf("config ID %q contains illegal characters", configID)
}

func hasOnlyAllowedChars(id string) bool {
    return id != "" && strings.TrimLeft(id, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-") == ""
}

if err := validateName(id); err != nil {
    return fmt.Errorf("config ID rejected: %w", err)
}

When it happens

Trigger: Including spaces, slashes, '@', unicode, or other special characters in a config group/value/policy key; pasting names with surrounding whitespace or URL-encoded characters into config.

Common situations: Organization or policy names containing spaces or symbols imported from external systems; shell scripts that leave untrimmed whitespace in names; JSON/YAML config with typo'd or decorated keys.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• config ID illegal, cannot be empty
• config ID illegal, cannot be longer than %d
• name '%s' for config ID is not allowed
• channel ID illegal, cannot be empty
• channel ID illegal, cannot be longer than %d

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