{"record":{"id":"98de48f2836bfeac","repo":"vitessio/vitess","slug":"inittablet-failed-because-existing-tablet-keyspace","errorCode":null,"errorMessage":"initTablet failed because existing tablet keyspace and shard %v/%v differ from the provided ones %v/%v","messagePattern":"initTablet failed because existing tablet keyspace and shard (.+?)/(.+?) differ from the provided ones (.+?)/(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vttablet/tabletmanager/tm_init.go","lineNumber":957,"sourceCode":"}\n\nfunc (tm *TabletManager) initTablet(ctx context.Context) error {\n\ttablet := tm.Tablet()\n\terr := tm.TopoServer.CreateTablet(ctx, tablet)\n\tswitch {\n\tcase err == nil:\n\t\t// It worked, we're good.\n\tcase topo.IsErrType(err, topo.NodeExists):\n\t\t// The node already exists, will just try to update\n\t\t// it. So we read it first.\n\t\toldTablet, err := tm.TopoServer.GetTablet(ctx, tablet.Alias)\n\t\tif err != nil {\n\t\t\treturn vterrors.Wrap(err, \"initTablet failed to read existing tablet record\")\n\t\t}\n\n\t\t// Sanity check the keyspace and shard\n\t\tif oldTablet.Keyspace != tablet.Keyspace || oldTablet.Shard != tablet.Shard {\n\t\t\treturn fmt.Errorf(\"initTablet failed because existing tablet keyspace and shard %v/%v differ from the provided ones %v/%v\", oldTablet.Keyspace, oldTablet.Shard, tablet.Keyspace, tablet.Shard)\n\t\t}\n\n\t\t// Update ShardReplication in any case, to be sure.  This is\n\t\t// meant to fix the case when a Tablet record was created, but\n\t\t// then the ShardReplication record was not (because for\n\t\t// instance of a startup timeout). Upon running this code\n\t\t// again, we want to fix ShardReplication.\n\t\tif updateErr := topo.UpdateTabletReplicationData(ctx, tm.TopoServer, tablet); updateErr != nil {\n\t\t\tlog.Error(fmt.Sprintf(\"UpdateTabletReplicationData failed for tablet %v: %v\", topoproto.TabletAliasString(tablet.Alias), updateErr))\n\t\t\treturn vterrors.Wrap(updateErr, \"UpdateTabletReplicationData failed\")\n\t\t}\n\t\tlog.Info(fmt.Sprintf(\"Successfully updated tablet replication data for alias: %v\", topoproto.TabletAliasString(tablet.Alias)))\n\n\t\t// Then overwrite everything, ignoring version mismatch.\n\t\tif err := tm.TopoServer.UpdateTablet(ctx, topo.NewTabletInfo(tablet, nil)); err != nil {\n\t\t\treturn vterrors.Wrap(err, \"UpdateTablet failed\")\n\t\t}\n\tdefault:","sourceCodeStart":939,"sourceCodeEnd":975,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vttablet/tabletmanager/tm_init.go#L939-L975","documentation":"initTablet refuses to start a tablet whose existing topo record belongs to a different keyspace/shard than the ones supplied at startup. Vitess checks this sanity invariant to prevent a tablet from silently joining the wrong shard, which would corrupt routing and replication topology. It is thrown when the pre-existing Tablet record in the topo server conflicts with the --keyspace/--shard flags.","triggerScenarios":"Calling vttablet Start (initTablet) when a Tablet record for the alias already exists in the topo with different Keyspace or Shard than the provided flags; e.g. re-pointing a tablet to another shard without deleting its old topo record.","commonSituations":"Operator moved a tablet between shards with vtctldclient but left a stale record; wrong --keyspace/--shard flags in the tablet's init config after a clone or restore; Kubernetes vttablet pod reusing a persistent alias with old metadata; disaster-recovery re-init with copied configs.","solutions":["Verify the keyspace/shard passed to the tablet process (flags or init params) match the intended topology","Check the existing tablet record: vtctldclient GetTablet <alias> and confirm its keyspace/shard","If the old record is stale, delete it with vtctldclient DeleteTablet <alias> and restart the tablet","If the flags are wrong, correct the deployment config (e.g. vttablet --keyspace/--shard or the operator's spec) and restart"],"exampleFix":"// before (tablet flags wrong for the shard)\nvttablet --init_keyspace=commerce --init_shard=0 ...\n// after (match the existing topo record, or first delete the stale record)\nvtctldclient DeleteTablet zone1-0000000100\nvttablet --init_keyspace=commerce --init_shard=1 ...","handlingStrategy":"validation","validationCode":"tablet, err := topo.GetTablet(ctx, alias)\nif err == nil && (tablet.Keyspace != wantKeyspace || tablet.Shard != wantShard) {\n    // stale record: delete or realign before starting\n    topo.DeleteTablet(ctx, alias)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"differ from the provided ones\") {\n    // inspect and reconcile keyspace/shard before retrying\n}","preventionTips":["Keep tablet alias-to-(keyspace,shard) mapping stable in deployment configs","Delete topo records when intentionally relocating a tablet between shards","Use VitessOperator or vtctldclient workflows rather than hand-edited tablet flags","Diff the tablet record (GetTablet) against init flags in pre-start checks"],"tags":["topology","tablet-init","config-mismatch"],"backgroundTag":"topo-record-mismatch","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}