vitessio/vitess · error

must specify action

Error message

must specify action

What it means

The shard-level HTTP handler accepts POST requests as shard actions; the 'action' form field selects which action to apply via ApplyShardAction. An empty action value produces this error, mirroring the keyspaces handler behavior.

Source

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

			return nil, fmt.Errorf("invalid shard path: %q", shardPath)
		}
		parts := strings.SplitN(shardPath, "/", 2)
		keyspace := parts[0]
		shard := parts[1]

		// List the shards in a keyspace.
		if shard == "" {
			return ts.GetShardNames(ctx, keyspace)
		}

		// Perform an action on a shard.
		if r.Method == "POST" {
			if err := r.ParseForm(); err != nil {
				return nil, err
			}
			action := r.FormValue("action")
			if action == "" {
				return nil, errors.New("must specify action")
			}
			return actions.ApplyShardAction(ctx, action, keyspace, shard), nil
		}

		// Get the shard record.
		si, err := ts.GetShard(ctx, keyspace, shard)
		if err != nil {
			return nil, err
		}
		// Pass the embedded proto directly or jsonpb will panic.
		return si.Shard, err
	})

	// SrvKeyspace
	handleCollection("srv_keyspace", func(r *http.Request) (any, error) {
		keyspacePath := getItemPath(r.URL.Path)
		parts := strings.SplitN(keyspacePath, "/", 2)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Include action=<name> in the POST form body with a shard action recognized by ApplyShardAction.
2. Send the body as application/x-www-form-urlencoded.
3. Log/inspect the request before sending to confirm the action string is populated.

Example fix

// before
curl -X POST http://localhost:15000/api/commerce/shards/0 -d ''
// after
curl -X POST http://localhost:15000/api/commerce/shards/0 -d 'action=RebuildKeyspaceGraph'

if action == "" {
    return fmt.Errorf("shard POST requires a non-empty 'action' form field")
}
form := url.Values{"action": {action}}

resp, err := http.PostForm(shardURL, form)
if err != nil || resp.StatusCode != http.StatusOK {
    // 'must specify action' - ensure action field present
}

When it happens

Trigger: POST to /api/<keyspace>/shards/<shard> (or /api/<keyspace>/tablets/<shard> path form) without an 'action' form field or with action= empty.

Common situations: Form field typo ('operation', 'cmd'); JSON body instead of form-encoded; scripts that compute the action conditionally and end up with an empty string.

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 must specify action
• cells can only be listed, not retrieved
• a POST request needs a keyspace in the URL
• keyspace is required
• no local cells have been created yet

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