vitessio/vitess · error · errors.ErrInvalidRequest

%w: shard name is required

Error message

%w: shard name is required

What it means

CreateShard requires req.ShardName to be non-empty; an empty shard name cannot identify a shard in the keyspace's shard ranges, so the function returns errors.ErrInvalidRequest wrapped with this message before acquiring the topo RW pool.

Source

Thrown at go/vt/vtadmin/cluster/cluster.go:477

	defer span.Finish()

	AnnotateSpan(c, span)

	if req == nil {
		return nil, fmt.Errorf("%w: request cannot be nil", errors.ErrInvalidRequest)
	}

	span.Annotate("keyspace", req.Keyspace)
	span.Annotate("shard", req.ShardName)
	span.Annotate("force", req.Force)
	span.Annotate("include_parent", req.IncludeParent)

	if req.Keyspace == "" {
		return nil, fmt.Errorf("%w: keyspace name is required", errors.ErrInvalidRequest)
	}

	if req.ShardName == "" {
		return nil, fmt.Errorf("%w: shard name is required", errors.ErrInvalidRequest)
	}

	if err := c.topoRWPool.Acquire(ctx); err != nil {
		return nil, fmt.Errorf("CreateShard(%+v) failed to acquire topoRWPool: %w", req, err)
	}
	defer c.topoRWPool.Release()

	return c.Vtctld.CreateShard(ctx, req)
}

// DeleteKeyspace deletes a keyspace in the given cluster, proxying a
// DeleteKeyspaceRequest to a vtctld in that cluster.
func (c *Cluster) DeleteKeyspace(ctx context.Context, req *vtctldatapb.DeleteKeyspaceRequest) (*vtctldatapb.DeleteKeyspaceResponse, error) {
	span, ctx := trace.NewSpan(ctx, "Cluster.DeleteKeyspace")
	defer span.Finish()

	AnnotateSpan(c, span)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Set req.ShardName to the desired shard name (e.g. "0", "-80", "c0-") before calling CreateShard.
2. Validate the shard name at your API boundary — non-empty and a valid keyrange/shard identifier.
3. If the shard name comes from a URL path, verify decoding preserved the full name (leading dashes especially).

Example fix

// before
req := &vtctldatapb.CreateShardRequest{Keyspace: "commerce"} // ShardName empty
// after
req := &vtctldatapb.CreateShardRequest{Keyspace: "commerce", ShardName: "-80"}

if req.ShardName == "" {
	return errors.New("shard name is required")
}
// optional: verify it parses as a shard/keyrange identifier
if _, err := key.ParseShardingSpec(req.ShardName); err != nil {
	return fmt.Errorf("invalid shard name %q: %w", req.ShardName, err)
}

resp, err := cluster.CreateShard(ctx, req)
if err != nil {
	if errors.Is(err, vtadminerrors.ErrInvalidRequest) {
		return status.Errorf(codes.InvalidArgument, "invalid shard request: %v", err)
	}
	return err
}

When it happens

Trigger: Calling Cluster.CreateShard with a request that has ShardName unset/empty, e.g. &vtctldatapb.CreateShardRequest{Keyspace: "commerce"} with no shard name.

Common situations: API consumers omitting the shard name in the request body; tooling splitting "keyspace/shard" strings incorrectly so the shard part is empty; dash/UTF-8 shard range names mangled by URL encoding on the way in.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• %w: request cannot be nil
• %w: keyspace name is required
• %w: cannot create shard in %s
• %w: cannot delete shards in %s
• %w: %s

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