vitessio/vitess · error · ErrInvalidRequest

%w: keyspace name is required

Error message

%w: keyspace name is required

What it means

Returned by vtadmin API methods (wrapping a sentinel error) when a request omits the required keyspace name, e.g. StartWorkflow/GetWorkflow calls on a keyspace-scoped resource.

Source

Thrown at go/vt/vtadmin/api.go:2615

	})
	if err != nil {
		return nil, err
	}

	return res, nil
}

// VExplain is part of the vtadminpb.VTAdminServer interface.
func (api *API) VExplain(ctx context.Context, req *vtadminpb.VExplainRequest) (*vtadminpb.VExplainResponse, error) {
	span, ctx := trace.NewSpan(ctx, "API.VExplain")
	defer span.Finish()

	if req.ClusterId == "" {
		return nil, fmt.Errorf("%w: clusterID is required", errors.ErrInvalidRequest)
	}

	if req.Keyspace == "" {
		return nil, fmt.Errorf("%w: keyspace name is required", errors.ErrInvalidRequest)
	}

	if req.Sql == "" {
		return nil, fmt.Errorf("%w: SQL query is required", errors.ErrInvalidRequest)
	}

	c, err := api.getClusterForRequest(req.ClusterId)
	if err != nil {
		return nil, err
	}

	if !api.authz.IsAuthorized(ctx, c.ID, rbac.VExplainResource, rbac.GetAction) {
		return nil, nil
	}

	// Parser with default options. New() itself initializes with default MySQL version.
	parser, err := sqlparser.New(sqlparser.Options{
		TruncateUILen:  512,

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Populate req.Keyspace with the target keyspace name
2. Fully qualify table names in SQL only as a complement — still set Keyspace as required by the API
3. Add client-side validation for keyspace presence

Example fix

// before
{clusterId: "prod-main", sql: "select * from t"}
// after
{clusterId: "prod-main", keyspace: "commerce", sql: "select * from t"}

if req.Keyspace == "" {
    return errors.New("keyspace is required for vexplain")
}

func hasKeyspace(req *vtadminpb.VExplainRequest) bool {
    return req != nil && req.Keyspace != ""
}

if !hasKeyspace(req) {
    return errors.New("keyspace is required for vexplain")
}
resp, err := client.VExplain(ctx, req)

When it happens

Trigger: Calling API.VExplain with ClusterId set but Keyspace equal to "".

Common situations: Query built from a context where the keyspace wasn't selected; UI sends the raw SQL without an attached keyspace; SQL already fully qualified but the API still requires the explicit keyspace field.

Related errors

• %w: clusterID is required
• %w: SQL query is required
• %w: request cannot be nil
• %w: keyspace name is required
• invalid joined path

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