vitessio/vitess · error

cells alias %v is not valid: %v

Error message

cells alias %v is not valid: %v

What it means

CreateCellsAlias validates the new alias (via validateAlias) before writing it to the topo and wraps any validation failure with this message. Common causes: alias name already exists, empty cell list, or the alias's cell set overlapping an existing alias's cells.

Source

Thrown at go/vt/topo/cells_aliases.go:122

func (ts *Server) DeleteCellsAlias(ctx context.Context, alias string) error {
	if ctx.Err() != nil {
		return ctx.Err()
	}
	ts.clearCellAliasesCache()

	filePath := pathForCellsAlias(alias)
	return ts.globalCell.Delete(ctx, filePath, nil)
}

// CreateCellsAlias creates a new CellInfo with the provided content.
func (ts *Server) CreateCellsAlias(ctx context.Context, alias string, cellsAlias *topodatapb.CellsAlias) error {
	currentAliases, err := ts.GetCellsAliases(ctx, true)
	if err != nil {
		return err
	}

	if err := validateAlias(currentAliases, alias, cellsAlias); err != nil {
		return fmt.Errorf("cells alias %v is not valid: %v", alias, err)
	}

	ts.clearCellAliasesCache()

	// Pack the content.
	contents, err := cellsAlias.MarshalVT()
	if err != nil {
		return err
	}

	// Save it.
	if ctx.Err() != nil {
		return ctx.Err()
	}
	filePath := pathForCellsAlias(alias)
	_, err = ts.globalCell.Create(ctx, filePath, contents)
	return err
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Run GetCellsAliases and check whether the alias name already exists; use UpdateCellsAlias instead to modify it.
2. Ensure each cell belongs to at most one alias — remove overlapping cells from the new alias.
3. Check the wrapped error for the specific validation rule that failed (duplicate name, overlap, empty list).

Example fix

// before
// cells_us = [cell1, cell2], creating:
CreateCellsAlias(ctx, "cells_us", &topodatapb.CellsAlias{Cells: []string{"cell2", "cell3"}}) // overlap: cell2
// after
CreateCellsAlias(ctx, "cells_us_west", &topodatapb.CellsAlias{Cells: []string{"cell3"}})

aliases, err := ts.GetCellsAliases(ctx, true)
if err != nil { return err }
if _, ok := aliases[alias]; ok {
    return errors.New("cells alias already exists; use update instead")
}
for name, a := range aliases {
    for _, c := range cellsAlias.Cells {
        if topo.InCellList(c, a.Cells) {
            return fmt.Errorf("cell %s already in alias %s", c, name)
        }
    }
}

if err := ts.CreateCellsAlias(ctx, alias, cellsAlias); err != nil {
    if strings.Contains(err.Error(), "not valid") {
        // inspect wrapped validateAlias error for duplicate/overlap cause
    }
    return err
}

When it happens

Trigger: Calling topo.Server.CreateCellsAlias (or vtctldclient AddCellsAlias) with an alias name that already exists, a cell list that overlaps an existing alias's cells, or otherwise invalid alias data.

Common situations: Operators defining region aliases (e.g. region1) in a multi-cell deployment; automation re-running an idempotency-unaware create; overlapping cells between geo aliases.

Related errors

• cell set overlaps with existing alias %v
• unknown topo protobuf type for %v
• GetKeyspaces: %w
• GetKeyspace(%v): %w
• fromTS.GetKeyspaces: %w

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