bytebase/bytebase · error

number_payload is required for column maximum character leng

Error message

number_payload is required for column maximum character length rule

What it means

The MySQL column maximum character length rule requires a number payload specifying the maximum allowed length (e.g. of VARCHAR/CHAR columns). Check() fails with this error when GetNumberPayload() returns nil, as there is no limit to enforce.

Source

Thrown at backend/plugin/advisor/mysql/rule_column_maximum_character_length.go:39

func init() {
	advisor.Register(storepb.Engine_MYSQL, storepb.SQLReviewRule_COLUMN_MAXIMUM_CHARACTER_LENGTH, &ColumnMaximumCharacterLengthAdvisor{})
	advisor.Register(storepb.Engine_MARIADB, storepb.SQLReviewRule_COLUMN_MAXIMUM_CHARACTER_LENGTH, &ColumnMaximumCharacterLengthAdvisor{})
	advisor.Register(storepb.Engine_OCEANBASE, storepb.SQLReviewRule_COLUMN_MAXIMUM_CHARACTER_LENGTH, &ColumnMaximumCharacterLengthAdvisor{})
}

// ColumnMaximumCharacterLengthAdvisor is the advisor checking for max character length.
type ColumnMaximumCharacterLengthAdvisor struct {
}

// Check checks for maximum character length.
func (*ColumnMaximumCharacterLengthAdvisor) Check(_ context.Context, checkCtx advisor.Context) ([]*storepb.Advice, error) {
	level, err := advisor.NewStatusBySQLReviewRuleLevel(checkCtx.Rule.Level)
	if err != nil {
		return nil, err
	}
	numberPayload := checkCtx.Rule.GetNumberPayload()
	if numberPayload == nil {
		return nil, errors.New("number_payload is required for column maximum character length rule")
	}

	rule := &columnMaximumCharacterLengthOmniRule{
		OmniBaseRule: OmniBaseRule{
			Level: level,
			Title: checkCtx.Rule.Type.String(),
		},
		maximum: int(numberPayload.Number),
	}

	for _, stmt := range checkCtx.ParsedStatements {
		if stmt.AST == nil {
			continue
		}
		node, ok := mysqlparser.GetOmniNode(stmt.AST)
		if !ok {
			continue
		}

View on GitHub (pinned to 1870550677)

Solutions

1. Populate Rule.Payload with a NumberPayload such as {"number": 255} before Check().
2. Ensure the JSON payload keys unmarshal into NumberPayload (protojson camelCase 'number').
3. Re-edit the SQL review rule and fill the numeric maximum field.

Example fix

// before
rule := &storepb.SQLReviewRule{Type: storepb.SQLReviewRuleType_COLUMN_MAXIMUM_CHARACTER_LENGTH, Level: storepb.SQLReviewRuleLevel_ERROR}
Check(ctx, &advisor.CheckContext{Rule: rule})

// after
payload, _ := protojson.Marshal(&storepb.NumberPayload{Number: 255})
rule := &storepb.SQLReviewRule{Type: storepb.SQLReviewRuleType_COLUMN_MAXIMUM_CHARACTER_LENGTH, Level: storepb.SQLReviewRuleLevel_ERROR, Payload: string(payload)}
Check(ctx, &advisor.CheckContext{Rule: rule})

if rule.GetNumberPayload() == nil {
    return fmt.Errorf("rule %s requires a number payload before Check()", rule.Type)
}

func hasNumberPayload(r *storepb.SQLReviewRule) bool { return r != nil && r.GetNumberPayload() != nil }

resp, err := advisor.Check(ctx, checkCtx)
if err != nil {
    if strings.Contains(err.Error(), "number_payload is required") {
        return nil, fmt.Errorf("rule %s is missing its max character length", checkCtx.Rule.Type)
    }
    return nil, err
}

When it happens

Trigger: Calling Check() with the MySQL column maximum character length rule while Rule.Payload is absent, empty JSON, or a different payload oneof than NumberPayload.

Common situations: Admin enabled the rule without specifying the max length; rule config migration lost the numeric field; caller building storepb.SQLReviewRule forgot the payload.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• number_payload is required for column auto increment initial
• number_payload is required for column maximum varchar length
• string_array_payload is required for column required rule
• number_payload is required for this rule
• number_payload is required for this rule

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/f5d4d5f28e60a0a7. Report an issue: GitHub.