vitessio/vitess · error

Unknown GC state: %s

Error message

Unknown GC state: %s

What it means

ParseGCLifecycle parses a comma/space-delimited --gc_lifecycle value by uppercasing each token and looking it up in gcStates. This error means one of the tokens is not a recognized GC state name (e.g. "hold,purp"), so the lifecycle set cannot be built.

Source

Thrown at go/vt/schema/tablegc.go:136

		return "", "", err
	}
	return fmt.Sprintf("RENAME TABLE `%s` TO %s", fromTableName, toTableName), toTableName, nil
}

// GenerateRenameStatement generates a "RENAME TABLE" statement, where a table is renamed to a GC table.
func GenerateRenameStatement(fromTableName string, state TableGCState, t time.Time) (statement string, toTableName string, err error) {
	return GenerateRenameStatementWithUUID(fromTableName, state, "", t)
}

// ParseGCLifecycle parses a comma separated list of gc states and returns a map of indicated states
func ParseGCLifecycle(gcLifecycle string) (states map[TableGCState]bool, err error) {
	states = make(map[TableGCState]bool)
	tokens := textutil.SplitDelimitedList(gcLifecycle)
	for _, token := range tokens {
		token = strings.ToUpper(token)
		state, ok := gcStates[token]
		if !ok {
			return states, fmt.Errorf("Unknown GC state: %s", token)
		}
		states[state] = true
	}
	// DROP is implicitly included.
	states[DropTableGCState] = true
	return states, nil
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Use valid state tokens: e.g. "hold,purge,drop" — check gcStates in go/vt/schema/tablegc.go for the exact set.
2. Fix the typo in the --gc_lifecycle flag in your tablet startup config.
3. If parsing programmatically, validate tokens against gcStates before calling ParseGCLifecycle.

Example fix

// before
tl.InitTablet("... --gc_lifecycle hold,purrg")
// after
tl.InitTablet("... --gc_lifecycle hold,purge")

for _, tok := range strings.Split(gcLifecycle, ",") {
    if _, ok := schema.GCStateNames[strings.ToUpper(strings.TrimSpace(tok))]; !ok {
        // fix the flag value before starting the tablet
    }
}

states, err := schema.ParseGCLifecycle(gcLifecycle)
if err != nil {
    return fmt.Errorf("invalid --gc_lifecycle: %w", err)
}

When it happens

Trigger: Setting the vttablet --gc_lifecycle flag (or lifecycle config reaching Open/newFakeDBTableGC) with an unrecognized token, e.g. --gc_lifecycle="drop,purrg"; tokens are uppercased before lookup so case itself is not the problem.

Common situations: Typo in tablet deployment flags/Helm charts; copying state names from older Vitess versions with renamed values; whitespace variants that SplitDelimitedList doesn't trim as expected.

Related errors

• error parsing %s: %w
• stray %% at the end of pattern
• overflow
• too many .s
• missing value for 'rate'

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