vitessio/vitess · error

cell param required

Error message

cell param required

What it means

In the tablets collection handler, when the request is not tablet-specific (no alias path) and no other filter applies, the code falls through to 'get all tablets in a cell'; an empty cell at that point means no cell could be determined, so the request is rejected with 'cell param required'.

Source

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

					return nil, err
				}
				if cell != "" {
					result, err := ts.FindAllTabletAliasesInShardByCell(ctx, keyspace, shard, []string{cell})
					if err != nil && !topo.IsErrType(err, topo.PartialResult) {
						return result, err
					}
					return result, nil
				}
				result, err := ts.FindAllTabletAliasesInShard(ctx, keyspace, shard)
				if err != nil && !topo.IsErrType(err, topo.PartialResult) {
					return result, err
				}
				return result, nil
			}

			// Get all tablets in a cell.
			if cell == "" {
				return nil, errors.New("cell param required")
			}
			return ts.GetTabletAliasesByCell(ctx, cell)
		}

		// Get tablet health.
		if parts := strings.Split(tabletPath, "/"); len(parts) == 2 && parts[1] == "health" {
			tabletAlias, err := topoproto.ParseTabletAlias(parts[0])
			if err != nil {
				return nil, err
			}
			return tabletHealthCache.Get(ctx, tabletAlias)
		}

		tabletAlias, err := topoproto.ParseTabletAlias(tabletPath)
		if err != nil {
			return nil, err
		}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Pass an explicit cell: GET /api/tablets?cell=<cell>.
2. Ensure the request originates from a vtctld with a configured local cell, or set the cell parameter explicitly.
3. To get a specific tablet, use its alias path (/api/tablets/<cell>-<uid>) instead.
4. Create cells in the topology if none exist (AddCellInfo) so listing can resolve a cell.

Example fix

// before
curl http://localhost:15000/api/tablets
// after
curl http://localhost:15000/api/tablets?cell=zone1

if cell == "" {
    return fmt.Errorf("cannot list tablets: cell parameter is required")
}
u := fmt.Sprintf("%s/api/tablets?cell=%s", base, url.QueryEscape(cell))

resp, err := http.Get(u)
if err != nil || strings.Contains(body, "cell param required") {
    // add ?cell=<name> and retry
}

When it happens

Trigger: GET /api/tablets (no tablet alias, no cell query param, and no local cell fallback available) reaching the GetTabletAliasesByCell call with cell == "" — e.g. a GET /api/tablets/health-free path shape that is not the health endpoint.

Common situations: Scripts omitting the cell query param; deployments without a local cell configured so the earlier fallback fails silently into this path; URL format mistakes dropping the cell segment.

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

• cells can only be listed, not retrieved
• a POST request needs a keyspace in the URL
• a POST request must specify action
• keyspace is required
• must specify action

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