vitessio/vitess · error

invalid format for <keyspace.workflow>: %s

Error message

invalid format for <keyspace.workflow>: %s

What it means

splitKeyspaceWorkflow parses the positional argument for vreplication workflow commands, which must be in the form <keyspace>.<workflow> with exactly one dot separating the two parts. Any input that does not split into exactly two segments is rejected. This is a pure input-format guard.

Source

Thrown at go/vt/vtctl/vtctl.go:2625

			wr.Logger().Printf("\nVDiff took %d seconds\n", int64(time.Since(now).Seconds()))
		}
	}()

	_, err = wr.VDiff(ctx, keyspace, workflow, *sourceCell, *targetCell, *tabletTypesStr, *filteredReplicationWaitTime, *format,
		*maxRows, *tables, *debugQuery, *onlyPks, *maxExtraRowsToCompare)
	if err != nil {
		log.Error(fmt.Sprintf("vdiff returning with error: %v", err))
		if strings.Contains(err.Error(), "context deadline exceeded") {
			return errors.New("vdiff timed out: you may want to increase it with the flag --filtered_replication_wait_time=<timeoutSeconds>")
		}
	}
	return err
}

func splitKeyspaceWorkflow(in string) (keyspace, workflow string, err error) {
	splits := strings.Split(in, ".")
	if len(splits) != 2 {
		return "", "", fmt.Errorf("invalid format for <keyspace.workflow>: %s", in)
	}
	return splits[0], splits[1], nil
}

func commandFindAllShardsInKeyspace(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	if err := subFlags.Parse(args); err != nil {
		return err
	}
	if subFlags.NArg() != 1 {
		return errors.New("the <keyspace> argument is required for the FindAllShardsInKeyspace command")
	}

	keyspace := subFlags.Arg(0)
	result, err := wr.VtctldServer().FindAllShardsInKeyspace(ctx, &vtctldatapb.FindAllShardsInKeyspaceRequest{
		Keyspace: keyspace,
	})
	if err != nil {
		return err

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Provide the argument as exactly `keyspace.workflow`, e.g. `commerce.reshard`
2. Ensure neither part contains a '.' character
3. Quote the argument in shell to avoid word-splitting surprises

Example fix

// before
vtctldclient Reshard cancel commerce
// after
vtctldclient Reshard cancel commerce.reshard

parts := strings.Split(arg, ".")
if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
  return errors.New("argument must be keyspace.workflow with no dots in either part")
}

func parseKeyspaceWorkflow(in string) (ks, wf string, ok bool) {
  p := strings.Split(in, ".")
  if len(p) != 2 || p[0] == "" || p[1] == "" { return "", "", false }
  return p[0], p[1], true
}

When it happens

Trigger: Passing `commerce` (missing .workflow), `commerce.reshard.extra` (extra dot), or an empty argument; keyspace or workflow names containing dots cannot be expressed in this format.

Common situations: Forgetting the workflow name; pasting a workflow UUID with dots; autocomplete inserting an extra segment; quoting mistakes in shell scripts.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• sample is too small
• BaseKeyspace is required for SNAPSHOT keyspaces
• the <tablet alias> argument is required for the SetReadWrite
• action StartReplication requires <tablet alias>
• action StopReplication requires <tablet alias>

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