vitessio/vitess · error

invalid Coercibility value

Error message

invalid Coercibility value

What it means

TypedCollation.String() (Collation's coercibility name method) panics when the Coercibility value is outside the defined 0-6 range. Coercibility is a small enum describing collation precedence; an out-of-range value means the value was constructed or deserialized incorrectly.

Source

Thrown at go/mysql/collations/coercion.go:79

func (ci Coercibility) String() string {
	switch ci {
	case 0:
		return "EXPLICIT"
	case 1:
		return "NONE"
	case 2:
		return "IMPLICIT"
	case 3:
		return "SYSCONST"
	case 4:
		return "COERCIBLE"
	case 5:
		return "NUMERIC"
	case 6:
		return "IGNORABLE"
	default:
		panic("invalid Coercibility value")
	}
}

// Repertoire is a constant that defines the collection of characters in an expression.
// MySQL only distinguishes between an ASCII repertoire (i.e. an expression where all
// the contained codepoints are < 128), or an Unicode repertoire (an expression that
// can contain any possible codepoint).
//
// See: https://dev.mysql.com/doc/refman/8.0/en/charset-repertoire.html
type Repertoire byte

const (
	RepertoireASCII Repertoire = iota
	RepertoireUnicode
)

// TypedCollation is the Collation of a SQL expression, including its coercibility
// and repertoire.

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check where the Coercibility value was produced; fix the packing/unpacking or initialization code.
2. Only construct Coercibility from the defined constants (CoercibilityExplicit ... CoercibilityIgnorable).
3. Add a validation in the constructor/deserializer to reject out-of-range values with a proper error.

Example fix

// before
c := Collation{Coercibility: Coercibility(9)}
fmt.Println(c.Coercibility) // panics
// after
c := Collation{Coercibility: CoercibilityIgnorable}
fmt.Println(c.Coercibility) // "IGNORABLE"

func validCoercibility(c collations.Coercibility) bool {
    return c >= collations.CoercibilityExplicit && c <= collations.CoercibilityIgnorable
}

func safeString(c collations.Coercibility) (s string) {
    defer func() {
        if r := recover(); r != nil {
            s = fmt.Sprintf("INVALID_COERCIBILITY(%d)", int(c))
        }
    }()
    return c.String()
}

When it happens

Trigger: Calling String() on a Coercibility value > 6 (or negative), typically from a corrupt/uninitialized TypedCollation, a bad bit-unpack, or a manually constructed Coercibility with an invalid integer.

Common situations: Debug printing of TypedCollation values decoded from an int32 that was corrupted; hand-written constants that don't match the enum; bit-packing bugs in code that serializes TypedCollation.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• listener must take exactly one input argument
• removing from wrong List
• TypedCollation should fit in an int32
• ReadFile cannot be called on read-write backup
• AddFile cannot be called on read-only backup

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/04d4f8a230cf08c1. Report an issue: GitHub.