vitessio/vitess · error

SnapshotTime is required for SNAPSHOT keyspaces

Error message

SnapshotTime is required for SNAPSHOT keyspaces

What it means

CreateKeyspace requires SNAPSHOT keyspaces to carry an explicit SnapshotTime, the point-in-time of the source keyspace the snapshot represents. Without it the snapshot has no defined temporal anchor, so the RPC rejects the request before creating any topology records.

Source

Thrown at go/vt/vtctl/grpcvtctldserver/server.go:938

	defer panicHandler(&err)

	span.Annotate("keyspace", req.Name)
	span.Annotate("keyspace_type", topoproto.KeyspaceTypeLString(req.Type))
	span.Annotate("force", req.Force)
	span.Annotate("allow_empty_vschema", req.AllowEmptyVSchema)
	span.Annotate("durability_policy", req.DurabilityPolicy)

	switch req.Type {
	case topodatapb.KeyspaceType_NORMAL:
	case topodatapb.KeyspaceType_SNAPSHOT:
		if req.BaseKeyspace == "" {
			err = errors.New("BaseKeyspace is required for SNAPSHOT keyspaces")
			return nil, err
		}

		if req.SnapshotTime == nil {
			err = errors.New("SnapshotTime is required for SNAPSHOT keyspaces")
			return nil, err
		}

		span.Annotate("base_keyspace", req.BaseKeyspace)
		span.Annotate("snapshot_time", protoutil.TimeFromProto(req.SnapshotTime).String())
	default:
		return nil, fmt.Errorf("unknown keyspace type %v", req.Type)
	}

	ki := &topodatapb.Keyspace{
		KeyspaceType:     req.Type,
		BaseKeyspace:     req.BaseKeyspace,
		SnapshotTime:     req.SnapshotTime,
		DurabilityPolicy: req.DurabilityPolicy,
		SidecarDbName:    req.SidecarDbName,
	}

	err = s.ts.CreateKeyspace(ctx, req.Name, ki)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Supply --snapshot-time (RFC3339) on the CLI or set req.SnapshotTime to a valid timestamp proto
2. Ensure BaseKeyspace is also set, since it is validated just before SnapshotTime
3. Use the source keyspace's recorded creation/snapshot timestamp if unknown

Example fix

// before
req := &vtctldatapb.CreateKeyspaceRequest{Type: topodatapb.KeyspaceType_SNAPSHOT, BaseKeyspace: "commerce"}
// after
req := &vtctldatapb.CreateKeyspaceRequest{
  Type: topodatapb.KeyspaceType_SNAPSHOT,
  BaseKeyspace: "commerce",
  SnapshotTime: timestamppb.New(time.Unix(1700000000, 0)),
}

if req.GetType() == topodatapb.KeyspaceType_SNAPSHOT && req.GetSnapshotTime() == nil {
    return fmt.Errorf("SnapshotTime must be set for SNAPSHOT keyspace %s", req.Name)
}

When it happens

Trigger: Calling CreateKeyspace with req.Type = topodatapb.KeyspaceType_SNAPSHOT and req.SnapshotTime == nil (CLI: --type=SNAPSHOT without a snapshot timestamp).

Common situations: Scripts that set BaseKeyspace but forget the timestamp; recovery/DR tooling reconstructing snapshot keyspaces from incomplete metadata; hand-written protobuf requests in tests.

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

• BaseKeyspace is required for SNAPSHOT keyspaces
• no shards found in keyspace
• a POST request needs a keyspace in the URL
• keyspace is required
• %w: keyspace name is required

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