{"record":{"id":"178d42169b6748dc","repo":"vitessio/vitess","slug":"shard-not-found","errorCode":null,"errorMessage":"shard not found","messagePattern":"shard not found","errorType":"error_code","errorClass":"ErrShardNotFound","httpStatus":null,"severity":"error","filePath":"go/vt/vtorc/inst/shard_dao.go","lineNumber":32,"sourceCode":"limitations under the License.\n*/\n\npackage inst\n\nimport (\n\t\"errors\"\n\t\"time\"\n\n\t\"vitess.io/vitess/go/protoutil\"\n\t\"vitess.io/vitess/go/vt/external/golib/sqlutils\"\n\ttopodatapb \"vitess.io/vitess/go/vt/proto/topodata\"\n\t\"vitess.io/vitess/go/vt/topo\"\n\t\"vitess.io/vitess/go/vt/topo/topoproto\"\n\t\"vitess.io/vitess/go/vt/vtorc/db\"\n)\n\n// ErrShardNotFound is a fixed error message used when a shard is not found in the database.\nvar ErrShardNotFound = errors.New(\"shard not found\")\n\n// ReadShardNames reads the names of vitess shards for a single keyspace.\nfunc ReadShardNames(keyspaceName string) (shardNames []string, err error) {\n\tshardNames = make([]string, 0)\n\tquery := `select shard from vitess_shard where keyspace = ?`\n\targs := sqlutils.Args(keyspaceName)\n\terr = db.QueryVTOrc(query, args, func(row sqlutils.RowMap) error {\n\t\tshardNames = append(shardNames, row.GetString(\"shard\"))\n\t\treturn nil\n\t})\n\treturn shardNames, err\n}\n\n// ReadShardPrimaryInformation reads the vitess shard record and gets the shard primary alias and timestamp.\nfunc ReadShardPrimaryInformation(keyspaceName, shardName string) (\n\tprimaryAlias *topodatapb.TabletAlias,\n\tprimaryTimestamp time.Time,\n\terr error,","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtorc/inst/shard_dao.go#L14-L50","documentation":"ErrShardNotFound is the sentinel error returned (e.g., by ReadShardPrimaryInformation) when the vitess shard record is missing from the database. It lets callers distinguish 'shard absent' from transient DB errors using errors.Is.","triggerScenarios":"Reading primary information for a keyspace/shard pair that has no row — shard not yet created, miscomputed shard name, or shard deleted from the topo.","commonSituations":"Wrong shard name format (e.g., missing dash range like '-' or wrong keyrange); vtorc watching a shard that was resharded away; race during resharding where the old shard record is removed.","solutions":["Verify shard existence with vtctldclient GetShard <keyspace>/<shard>.","Correct the shard name (use topoproto or ShardName formatting conventions).","If resharding removed the shard, update vtorc's clusters-to-watch configuration to the new shard names."],"exampleFix":"// before\nprim, err := inst.ReadShardPrimaryInformation(keyspace, shard)\nif err != nil { return err }\n// after\nprim, err := inst.ReadShardPrimaryInformation(keyspace, shard)\nif errors.Is(err, inst.ErrShardNotFound) {\n    return fmt.Errorf(\"shard %s/%s not found; verify shard name and topology\", keyspace, shard)\n} else if err != nil { return err }","handlingStrategy":"validation","validationCode":"if keyspace == \"\" || shard == \"\" {\n    return errors.New(\"keyspace and shard are required\")\n}\n// verify shard exists via topo server before reading primary info","typeGuard":null,"tryCatchPattern":"prim, err := inst.ReadShardPrimaryInformation(keyspace, shard)\nif errors.Is(err, inst.ErrShardNotFound) {\n    return handleMissingShard(keyspace, shard)\n} else if err != nil { return err }","preventionTips":["Use canonical shard-name formatting (e.g., '-' for unsharded, low-high ranges).","Update vtorc clusters-to-watch after resharding operations.","Use errors.Is against ErrShardNotFound rather than string comparison."],"tags":["vtorc","shard","not-found","topology"],"backgroundTag":"entity-not-found","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}