vitessio/vitess · error

Error parsing --table-gc-lifecycle flag: %+v

Error message

Error parsing --table-gc-lifecycle flag: %+v

What it means

Raised during tabletserver (TableGC) Open when the --table-gc-lifecycle flag string cannot be parsed by schema.ParseGCLifecycle. The flag must be a comma-separated list of valid GC lifecycle states (e.g. hold,purge,evac,drop); anything invalid aborts the TableGC collector startup.

Source

Thrown at go/vt/vttablet/tabletserver/gc/tablegc.go:193

	collector.shard = shard
	collector.dbName = dbName
}

// Open opens database pool and initializes the schema
func (collector *TableGC) Open() (err error) {
	collector.stateMutex.Lock()
	defer collector.stateMutex.Unlock()
	if collector.isOpen > 0 {
		// already open
		return nil
	}
	if !collector.env.Config().EnableTableGC {
		return nil
	}

	collector.lifecycleStates, err = schema.ParseGCLifecycle(gcLifecycle)
	if err != nil {
		return fmt.Errorf("Error parsing --table-gc-lifecycle flag: %+v", err)
	}

	log.Info("TableGC: opening")
	collector.pool.Open(collector.env.Config().DB.AllPrivsWithDB(), collector.env.Config().DB.DbaWithDB(), collector.env.Config().DB.AppDebugWithDB())
	atomic.StoreInt64(&collector.isOpen, 1)

	conn, err := dbconnpool.NewDBConnection(context.Background(), collector.env.Config().DB.AllPrivsWithDB())
	if err != nil {
		return err
	}
	defer conn.Close()
	collector.lifecycleStates, err = adjustLifecycleForFastDrops(conn, collector.lifecycleStates)
	if err != nil {
		return err
	}
	log.Info(fmt.Sprintf("TableGC: MySQL version=%v, lifecycleStates=%v", conn.ServerVersion, collector.lifecycleStates))

	ctx := context.Background()

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix --table-gc-lifecycle to a valid comma-separated list of supported states (e.g. 'purge,evac,drop')
2. Check the wrapped %+v error in the message for the exact offending token
3. Verify allowed state names against schema.ParseGCLifecycle for your Vitess version
4. Remove the flag to use the default lifecycle set

Example fix

// before
--table-gc-lifecycle "purge; evac"
// after
--table-gc-lifecycle "purge,evac"

// validate before launch
if os.Getenv("TABLE_GC_LIFECYCLE") != "" {
    if _, err := schema.ParseGCLifecycle(os.Getenv("TABLE_GC_LIFECYCLE")); err != nil {
        panic(fmt.Sprintf("bad --table-gc-lifecycle: %v", err))
    }
}

When it happens

Trigger: Starting vttablet (or env.Config call path) with --table-gc-lifecycle containing a typo'd or unknown state name, wrong separator (spaces/semicolons), or malformed syntax so ParseGCLifecycle returns an error.

Common situations: Config mistakes after renaming lifecycle states across Vitess versions; copy-pasted flag values from docs of a different version; trailing commas or whitespace-only entries.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• unsupported balancer policy %s; must be one of %s
• cell mode should be handled by the gateway, not the balancer
• package %s is not under %s
• unknown handling name %s
• cannot build vschema for keyspace %v: %v

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