vitessio/vitess · error

SaveVSchema(%v) = %w

Error message

SaveVSchema(%v) = %w

What it means

When creating a SNAPSHOT keyspace, the server saves a synthetic serving VSchema (with RequireExplicitRouting so it is excluded from global routing) to the topo. If SaveVSchema fails (topo backend error), the error is wrapped as SaveVSchema(%v) = %w and CreateKeyspace aborts.

Source

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

				}
			} else {
				return nil, err
			}
		}

		// We don't want to clone the base keyspace's key version
		// so we do NOT call bksvs.CloneVT() here. We instead only
		// clone the vschemapb.Keyspace field for the new snapshot
		// keyspace.
		sksvs := &topo.KeyspaceVSchemaInfo{
			Name:     req.Name,
			Keyspace: bksvs.Keyspace.CloneVT(),
		}
		// SNAPSHOT keyspaces are excluded from global routing.
		sksvs.RequireExplicitRouting = true

		if err = s.ts.SaveVSchema(ctx, sksvs); err != nil {
			return nil, fmt.Errorf("SaveVSchema(%v) = %w", sksvs, err)
		}
	}

	cells := []string{}
	err = s.ts.RebuildSrvVSchema(ctx, cells)
	if err != nil {
		return nil, fmt.Errorf("RebuildSrvVSchema(%v) = %w", cells, err)
	}

	return &vtctldatapb.CreateKeyspaceResponse{
		Keyspace: &vtctldatapb.Keyspace{
			Name:     req.Name,
			Keyspace: ki,
		},
	}, nil
}

// CreateShard is part of the vtctlservicepb.VtctldServer interface.

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the wrapped cause (%w) for the actual topo error and fix connectivity/permissions
2. Verify the topo server is healthy and writable by vtctld
3. Retry CreateKeyspace after the transient topo issue is resolved
4. Confirm a partially-created keyspace is cleaned up before retrying

if err := ts.Health(ctx); err != nil {
    return fmt.Errorf("topo unavailable, defer keyspace creation: %w", err)
}

_, err := client.CreateKeyspace(ctx, req)
if err != nil && strings.Contains(err.Error(), "SaveVSchema") {
    // check topo connectivity/permissions, then retry
}

When it happens

Trigger: Creating a SNAPSHOT keyspace when the underlying topo write fails: topo server unavailable, permission denied, keyspace record conflict, or connection timeouts to etcd/ZooKeeper.

Common situations: etcd/ZK outage or saturation during keyspace creation; read-only topo credentials; network partition between vtctld and topo server.

Related errors

• failed to get source keyspace vschema: %v
• GetVSchema(keyspace = %s): %w
• EnsureVSchema(%v) failed: %v
• RebuildSrvVSchema(%v) = %w
• value must be either a float64 (interpreted as seconds) or a

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