What causes "shard not found" in vitessio/vitess?

Verify shard existence with vtctldclient GetShard / .

vitessio/vitess · error · ErrShardNotFound

shard not found

Error message

shard not found

What it means

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.

Source

Thrown at go/vt/vtorc/inst/shard_dao.go:32

limitations under the License.
*/

package inst

import (
	"errors"
	"time"

	"vitess.io/vitess/go/protoutil"
	"vitess.io/vitess/go/vt/external/golib/sqlutils"
	topodatapb "vitess.io/vitess/go/vt/proto/topodata"
	"vitess.io/vitess/go/vt/topo"
	"vitess.io/vitess/go/vt/topo/topoproto"
	"vitess.io/vitess/go/vt/vtorc/db"
)

// ErrShardNotFound is a fixed error message used when a shard is not found in the database.
var ErrShardNotFound = errors.New("shard not found")

// ReadShardNames reads the names of vitess shards for a single keyspace.
func ReadShardNames(keyspaceName string) (shardNames []string, err error) {
	shardNames = make([]string, 0)
	query := `select shard from vitess_shard where keyspace = ?`
	args := sqlutils.Args(keyspaceName)
	err = db.QueryVTOrc(query, args, func(row sqlutils.RowMap) error {
		shardNames = append(shardNames, row.GetString("shard"))
		return nil
	})
	return shardNames, err
}

// ReadShardPrimaryInformation reads the vitess shard record and gets the shard primary alias and timestamp.
func ReadShardPrimaryInformation(keyspaceName, shardName string) (
	primaryAlias *topodatapb.TabletAlias,
	primaryTimestamp time.Time,
	err error,

View on GitHub (pinned to 01a25a7d17)

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.

Example fix

// before
prim, err := inst.ReadShardPrimaryInformation(keyspace, shard)
if err != nil { return err }
// after
prim, err := inst.ReadShardPrimaryInformation(keyspace, shard)
if errors.Is(err, inst.ErrShardNotFound) {
    return fmt.Errorf("shard %s/%s not found; verify shard name and topology", keyspace, shard)
} else if err != nil { return err }

Defensive patterns

Strategy: validation

Validate before calling

if keyspace == "" || shard == "" {
    return errors.New("keyspace and shard are required")
}
// verify shard exists via topo server before reading primary info

Try / catch

prim, err := inst.ReadShardPrimaryInformation(keyspace, shard)
if errors.Is(err, inst.ErrShardNotFound) {
    return handleMissingShard(keyspace, shard)
} else if err != nil { return err }

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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