invalid init-tablet-type %v; can only be REPLICA, RDONLY, EX

Error message

invalid init-tablet-type %v; can only be REPLICA, RDONLY, EXPERIMENTAL or SPARE

What it means

BuildTabletFromInput validates the --init_tablet_type flag when vttablet initializes a new tablet record. Only REPLICA, RDONLY, EXPERIMENTAL or SPARE are allowed; PRIMARY-like or invalid values are rejected because initial type must not be a serving-primary type.

Source

Thrown at go/vt/vttablet/tabletmanager/tm_init.go:271

	if initKeyspace == "" || initShard == "" {
		return nil, errors.New("init-keyspace and init-shard must be specified")
	}

	// parse and validate shard name
	shard, keyRange, err := topo.ValidateShardName(initShard)
	if err != nil {
		return nil, vterrors.Wrapf(err, "cannot validate shard name %v", initShard)
	}

	tabletType, err := topoproto.ParseTabletType(initTabletType)
	if err != nil {
		return nil, err
	}
	switch tabletType {
	case topodatapb.TabletType_SPARE, topodatapb.TabletType_REPLICA, topodatapb.TabletType_RDONLY, topodatapb.TabletType_EXPERIMENTAL:
	default:
		return nil, fmt.Errorf("invalid init-tablet-type %v; can only be REPLICA, RDONLY, EXPERIMENTAL or SPARE", tabletType)
	}

	buildTags, err := getBuildTags(servenv.AppVersion.ToStringMap(), skipBuildInfoTags)
	if err != nil {
		return nil, err
	}

	var charset collations.ID
	if db != nil && db.Charset != "" {
		charset, err = collationEnv.ParseConnectionCharset(db.Charset)
		if err != nil {
			return nil, err
		}
	} else {
		charset = collationEnv.DefaultConnectionCharset()
	}

	return &topodatapb.Tablet{

View on GitHub (pinned to 01a25a7d17)

Solutions

Set --init_tablet_type=REPLICA (the most common choice) or RDONLY/SPARE as appropriate
Promote to primary afterwards via InitPrimary/PlannedRecoveryType instead of initializing as primary
Fix any leftover 'MASTER' values in manifests — use REPLICA and let topology handle promotion
Validate the flag value before deployment to catch typos

Example fix

// before
vttablet --init_tablet_type=MASTER ...
// after
vttablet --init_tablet_type=REPLICA ...

Defensive patterns

Strategy: validation

Validate before calling

var validInitTypes = map[string]bool{"REPLICA": true, "RDONLY": true, "EXPERIMENTAL": true, "SPARE": true}
if !validInitTypes[strings.ToUpper(initTabletType)] {
    return fmt.Errorf("--init_tablet_type must be REPLICA, RDONLY, EXPERIMENTAL or SPARE, got %q", initTabletType)
}

Try / catch

if err := startVttablet(flags); err != nil && strings.Contains(err.Error(), "invalid init-tablet-type") {
    // fix the flag in the deployment manifest and restart
}

Prevention

Lint deployment manifests against valid flag values
Never use MASTER/PRIMARY for --init_tablet_type; promote later instead
Default to REPLICA unless a batch/serving tier is intended
Validate flags in CI config tests before rollout

When it happens

Trigger: Starting vttablet with --init_tablet_type set to something other than REPLICA, RDONLY, EXPERIMENTAL or SPARE (e.g. PRIMARY, MASTER, or a typo).

Common situations: Copy-paste of old configs using the removed MASTER value, operators trying to init a tablet as PRIMARY directly, typos in deployment manifests.

Related errors

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