hyperledger/fabric · error

'%s' contains illegal characters

Error message

'%s' contains illegal characters

What it means

ValidateChannelID checks the channel ID against ChannelAllowedChars via regexp; if the whole string is not a full match, it contains illegal characters. Allowed characters are lowercase alphanumerics plus '-' and '.' per Fabric's channel naming rules.

Source

Thrown at core/tx/endorser/parser.go:207

// 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 common/configtx/validator.go
func ValidateChannelID(channelID string) error {
	re, _ := regexp.Compile(ChannelAllowedChars)
	// Length
	if len(channelID) <= 0 {
		return errors.Errorf("channel ID illegal, cannot be empty")
	}
	if len(channelID) > MaxLength {
		return errors.Errorf("channel ID illegal, cannot be longer than %d", MaxLength)
	}

	// Illegal characters
	matched := re.FindString(channelID)
	if len(matched) != len(channelID) {
		return errors.Errorf("'%s' contains illegal characters", channelID)
	}

	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Normalize the name to lowercase and replace illegal characters with '-' before use.
2. Enforce the pattern ^[a-z][a-z0-9.-]*$ in your naming utility at creation time.
3. Use names of only lowercase letters, digits, '.', and '-' (and start with a letter per convention).

Example fix

// before
name := strings.ToUpper("my_channel")
// after
re := regexp.MustCompile(`[^a-z0-9.-]`)
name := strings.ToLower(re.ReplaceAllString("my_channel", "-"))

if !regexp.MustCompile(`^[a-z][a-z0-9.-]*$`).MatchString(channelID) { return fmt.Errorf("channel ID %q has illegal characters", channelID) }

var chRe = regexp.MustCompile(`^[a-z][a-z0-9.-]*$`)
func channelIDCharsOK(id string) bool { return chRe.MatchString(id) }

When it happens

Trigger: Using uppercase letters, underscores, spaces, slashes, or unicode in a channel name — e.g. "MyChannel", "my_channel", "org1/channel".

Common situations: Deriving channel names from branch names containing '/', underscores, or uppercase (git branches like feature/XYZ); user-supplied names not sanitized; docker-compose env values with invalid chars.

Related errors

• channel ID illegal, cannot be empty
• channel ID illegal, cannot be longer than %d
• %s is mandatory and cannot be empty
• enrollment certificate isn't a valid PEM block
• failed to decode PEM block from %s

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