{"record":{"id":"8fef20d556f42500","repo":"vitessio/vitess","slug":"cannot-get-or-create-shard-v-v-v","errorCode":null,"errorMessage":"cannot get (or create) shard %v/%v: %v","messagePattern":"cannot get \\(or create\\) shard (.+?)/(.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/topo/tablet.go","lineNumber":616,"sourceCode":"\ttablet.Shard = shard\n\ttablet.KeyRange = kr\n\n\t// get the shard, possibly creating it\n\tvar si *ShardInfo\n\n\tif createShardAndKeyspace {\n\t\t// create the parent keyspace and shard if needed\n\t\tsi, err = ts.GetOrCreateShard(ctx, tablet.Keyspace, tablet.Shard)\n\t} else {\n\t\tsi, err = ts.GetShard(ctx, tablet.Keyspace, tablet.Shard)\n\t\tif IsErrType(err, NoNode) {\n\t\t\treturn errors.New(\"missing parent shard, use -parent option to create it, or CreateKeyspace / CreateShard\")\n\t\t}\n\t}\n\n\t// get the shard, checks a couple things\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot get (or create) shard %v/%v: %v\", tablet.Keyspace, tablet.Shard, err)\n\t}\n\tif !key.KeyRangeEqual(si.KeyRange, tablet.KeyRange) {\n\t\treturn fmt.Errorf(\"shard %v/%v has a different KeyRange: %v != %v\", tablet.Keyspace, tablet.Shard, si.KeyRange, tablet.KeyRange)\n\t}\n\tif tablet.Type == topodatapb.TabletType_PRIMARY && si.HasPrimary() && !topoproto.TabletAliasEqual(si.PrimaryAlias, tablet.Alias) && !allowPrimaryOverride {\n\t\t// InitTablet is deprecated, so the flag has not been renamed\n\t\treturn fmt.Errorf(\"creating this tablet would override old primary %v in shard %v/%v, use allow_master_override flag\", topoproto.TabletAliasString(si.PrimaryAlias), tablet.Keyspace, tablet.Shard)\n\t}\n\n\tif tablet.Type == topodatapb.TabletType_PRIMARY {\n\t\t// we update primary_term_start_time even if the primary hasn't changed\n\t\t// because that means a new primary term with the same primary\n\t\ttablet.PrimaryTermStartTime = protoutil.TimeToProto(time.Now())\n\t}\n\n\terr = ts.CreateTablet(ctx, tablet)\n\tif IsErrType(err, NodeExists) && allowUpdate {\n\t\t// Try to update then","sourceCodeStart":598,"sourceCodeEnd":634,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/topo/tablet.go#L598-L634","documentation":"InitTablet registers a tablet record and fetches/creates its parent shard first. This error is thrown when the get-or-create of shard <keyspace>/<shard> itself failed — the shard record could be neither read nor created in the topo. It aborts tablet registration because a tablet must belong to an existing shard record.","triggerScenarios":"Calling InitTablet (or legacy addTablet / vttablet startup with -init_shard creation path) when GetShard fails for a reason other than 'not found', or CreateShard fails (keyspace missing without -parent, topo write error, concurrent creation).","commonSituations":"Starting a vttablet before the keyspace/shard was created and without -parent; topo connectivity outage during tablet boot; wrong -keyspace/-shard spelling pointing at a nonexistent keyspace; topo RBAC blocking shard creation.","solutions":["Pre-create the hierarchy: `vtctldclient CreateKeyspace` then `vtctldclient CreateShard` before starting the tablet, or pass -parent so InitTablet creates the shard.","Fix the keyspace/shard name on the tablet's flags — a typo makes it point at a keyspace that does not exist.","Check the wrapped inner error: topo unreachable → fix topo flags/connectivity; permission denied → fix topo ACLs.","Retry tablet startup once the topo is healthy; InitTablet is safe to re-run for a non-primary tablet."],"exampleFix":"// before (tablet started before topology exists)\nvttablet -keyspace commerce -shard \"-\" ...   // cannot get (or create) shard\n// after\nvtctldclient CreateKeyspace commerce\nvtctldclient CreateShard commerce \"-\"\nvttablet -keyspace commerce -shard \"-\" -parent ...","handlingStrategy":"validation","validationCode":"// Before starting a tablet, confirm shard exists\nsi, err := ts.GetShard(ctx, keyspace, shard)\nif err != nil {\n    return fmt.Errorf(\"create keyspace/shard %s/%s first: %w\", keyspace, shard, err)\n}","typeGuard":null,"tryCatchPattern":"if err := topotools.InitTablet(ctx, ts, allowPrimary, tablet, cp); err != nil {\n    if strings.Contains(err.Error(), \"cannot get (or create) shard\") {\n        // create the keyspace/shard, then retry\n        _ = ts.CreateShard(ctx, keyspace, shard)\n        err = topotools.InitTablet(ctx, ts, allowPrimary, tablet, cp)\n    }\n    return err\n}","preventionTips":["Create keyspace and shard before launching vttablets (or always pass -parent).","Template tablet startup configs from the shard plan to avoid name typos.","Check topo connectivity from tablets at boot.","Use vtctldclient GetShard as a pre-flight check in startup scripts."],"tags":["topo","tablet","shard","initialization"],"backgroundTag":"shard-not-found","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}