bytebase/bytebase · error

invalid template token %s for rule %s

Error message

invalid template token %s for rule %s

What it means

For template naming rules, the Format string is parsed into template tokens (e.g. {table}, {column}) and every token must be one advisor.TemplateNamingTokens allows for that specific rule type. An unknown or not-applicable token aborts validation with this error.

Source

Thrown at backend/api/v1/review_config_service.go:383

			return errors.Errorf("naming rule max_length cannot be negative for rule %s, got %d", ruleType, payload.MaxLength)
		}

	// Naming rules with template token validation
	case storepb.SQLReviewRule_NAMING_INDEX_FK, storepb.SQLReviewRule_NAMING_INDEX_IDX, storepb.SQLReviewRule_NAMING_INDEX_UK, storepb.SQLReviewRule_NAMING_INDEX_PK, storepb.SQLReviewRule_TABLE_DROP_NAMING_CONVENTION:
		payload := rule.GetNamingPayload()
		if payload == nil {
			return errors.Errorf("rule %s requires naming payload", ruleType)
		}
		// At least one of format or maxLength must be set
		if payload.Format == "" && payload.MaxLength <= 0 {
			return errors.Errorf("naming rule must specify either format or max_length for rule %s", ruleType)
		}
		// If format is set, validate template tokens
		if payload.Format != "" {
			tokens, _ := advisor.ParseTemplateTokens(payload.Format)
			for _, token := range tokens {
				if _, ok := advisor.TemplateNamingTokens[ruleType][token]; !ok {
					return errors.Errorf("invalid template token %s for rule %s", token, ruleType)
				}
			}
		}
		// If maxLength is set, validate it's positive (maxLength == 0 means not set)
		if payload.MaxLength < 0 {
			return errors.Errorf("naming rule max_length cannot be negative for rule %s, got %d", ruleType, payload.MaxLength)
		}

	// Number payload rules
	case storepb.SQLReviewRule_STATEMENT_INSERT_ROW_LIMIT,
		storepb.SQLReviewRule_STATEMENT_AFFECTED_ROW_LIMIT,
		storepb.SQLReviewRule_STATEMENT_WHERE_MAXIMUM_LOGICAL_OPERATOR_COUNT,
		storepb.SQLReviewRule_STATEMENT_MAXIMUM_STATEMENTS_IN_TRANSACTION,
		storepb.SQLReviewRule_BUILTIN_STATEMENT_MAXIMUM_SQL_SIZE,
		storepb.SQLReviewRule_COLUMN_MAXIMUM_CHARACTER_LENGTH,
		storepb.SQLReviewRule_COLUMN_MAXIMUM_VARCHAR_LENGTH,
		storepb.SQLReviewRule_COLUMN_AUTO_INCREMENT_INITIAL_VALUE,
		storepb.SQLReviewRule_INDEX_KEY_NUMBER_LIMIT,

View on GitHub (pinned to 1870550677)

Solutions

1. Use only tokens listed for the rule type in advisor.TemplateNamingTokens (e.g. {table} for index rules)
2. Check the advisor package docs/source for the allowed token set per rule
3. Remove the offending token or switch to a rule type that supports it

Example fix

// before
{type: "NAMING_INDEX_PK", namingPayload: {format: "pk_{column}"}}
// after
{type: "NAMING_INDEX_PK", namingPayload: {format: "pk_{table}"}}

if p := rule.GetNamingPayload(); p != nil && p.Format != "" {
  tokens, _ := advisor.ParseTemplateTokens(p.Format)
  for _, t := range tokens {
    if _, ok := advisor.TemplateNamingTokens[storepb.SQLReviewRule_RuleType(rule.Type)][t]; !ok {
      return fmt.Errorf("token %s not allowed for %s", t, rule.Type)
    }
  }
}

func tokensAllowed(ruleType storepb.SQLReviewRule_RuleType, format string) bool {
  tokens, _ := advisor.ParseTemplateTokens(format)
  for _, t := range tokens {
    if _, ok := advisor.TemplateNamingTokens[ruleType][t]; !ok { return false }
  }
  return true
}

err := updateReviewConfig(ctx, req)
if err != nil && strings.Contains(err.Error(), "invalid template token") {
  // show the allowed token list for the rule type and re-open the template editor
}

When it happens

Trigger: CreateReviewConfig/UpdateReviewConfig with a template naming rule whose format uses a token not defined for that rule, e.g. NAMING_INDEX_PK with format "pk_{column}" when {column} is not a valid token for that rule.

Common situations: Users guessing at template placeholders; copying a format from one naming rule to another where the token vocabulary differs; typos like {tablename} instead of {table}.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• template must contain {iteration} placeholder
• {iteration} must be at the end of the template
• template must contain at least one of: {date}, {time}, {time
• naming rule must specify either format or max_length for rul
• invalid naming rule format pattern %q for rule %s

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