vitessio/vitess · error

keyspace is required

Error message

keyspace is required

What it means

The shards HTTP API routes requests of the form /api/<keyspace>/tablets[/<shard>]. If the first path segment (the keyspace) is empty the handler rejects the request with 'keyspace is required' before resolving shards. It is a request-validation error produced when the URL path is malformed.

Source

Thrown at go/vt/vtctld/api.go:245

	})

	handleCollection("keyspace", func(r *http.Request) (any, error) {
		// Valid requests: api/keyspace/my_ks/tablets (all shards)
		// Valid requests: api/keyspace/my_ks/tablets/-80 (specific shard)
		itemPath := getItemPath(r.URL.Path)
		parts := strings.SplitN(itemPath, "/", 3)

		malformedRequestError := fmt.Errorf("invalid keyspace path: %q  expected path: /keyspace/<keyspace>/tablets or /keyspace/<keyspace>/tablets/<shard>", itemPath)
		if len(parts) < 2 {
			return nil, malformedRequestError
		}
		if parts[1] != "tablets" {
			return nil, malformedRequestError
		}

		keyspace := parts[0]
		if keyspace == "" {
			return nil, errors.New("keyspace is required")
		}
		var shardNames []string
		if len(parts) > 2 && parts[2] != "" {
			shardNames = []string{parts[2]}
		} else {
			var err error
			shardNames, err = ts.GetShardNames(ctx, keyspace)
			if err != nil {
				return nil, err
			}
		}

		if err := r.ParseForm(); err != nil {
			return nil, err
		}
		cell := r.FormValue("cell")
		cells := r.FormValue("cells")
		filterCells := []string{} // empty == all cells

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Build the URL with the keyspace: GET /api/<keyspace>/tablets (optionally /api/<keyspace>/tablets/<shard>).
2. Validate the keyspace value is non-empty before constructing the URL in your client code.
3. Check upstream data feeding the script — the keyspace may be missing because of an earlier failed API call.

Example fix

// before
curl http://localhost:15000/api//tablets
// after
curl http://localhost:15000/api/commerce/tablets

if keyspace == "" {
    return fmt.Errorf("cannot build tablets URL: keyspace is required")
}
path := fmt.Sprintf("/api/%s/tablets", keyspace)

resp, err := http.Get(base + path)
if err != nil || resp.StatusCode == http.StatusBadRequest {
    // 'keyspace is required' - check the keyspace segment of the URL
}

When it happens

Trigger: Requesting a path like /api//tablets or /api/tablets where the keyspace segment is empty; programmatically built URLs with an empty keyspace variable.

Common situations: Template/format-string bugs where the keyspace variable was not interpolated; clients migrated from vtctl where a default keyspace was assumed; truncated URLs.

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

• a POST request needs a keyspace in the URL
• BaseKeyspace is required for SNAPSHOT keyspaces
• SnapshotTime is required for SNAPSHOT keyspaces
• no shards found in keyspace
• cells can only be listed, not retrieved

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