--direction requires --sort to be one of %s; position (the d

Error message

--direction requires --sort to be one of %s; position (the default manual board order) is always ascending

What it means

--direction was passed but --sort is either empty or 'position'. Position is the manual board order and is always ascending — the server ignores --direction for it — so the CLI rejects the combination up front rather than silently dropping a flag the user explicitly passed. The message names the sort columns that do accept a direction (directionalIssueSortColumns).

Source

Thrown at server/cmd/multica/cmd_issue.go:663

				break
			}
		}
		if !valid {
			return fmt.Errorf("invalid --sort %q; valid values: %s", sortVal, strings.Join(validIssueSortColumns, ", "))
		}
		params.Set("sort", sortVal)
	}
	if v, _ := cmd.Flags().GetString("direction"); v != "" {
		d := strings.ToLower(v)
		if d != "asc" && d != "desc" {
			return fmt.Errorf("invalid --direction %q; valid values: asc, desc", v)
		}
		// position (the manual board order) is always ascending, so the server
		// ignores --direction for it. Reject the combination up front rather
		// than silently dropping the flag — a passed-but-ignored flag is a
		// footgun, especially in scripts.
		if sortVal == "" || sortVal == "position" {
			return fmt.Errorf("--direction requires --sort to be one of %s; position (the default manual board order) is always ascending", strings.Join(directionalIssueSortColumns, ", "))
		}
		params.Set("direction", d)
	}

	path := "/api/issues"
	if len(params) > 0 {
		path += "?" + params.Encode()
	}

	var result map[string]any
	if err := client.GetJSON(ctx, path, &result); err != nil {
		return fmt.Errorf("list issues: %w", err)
	}

	issuesRaw, _ := result["issues"].([]any)

	output, _ := cmd.Flags().GetString("output")
	if output == "json" {

View on GitHub (pinned to 2c0912b6ec)

Solutions

Pair --direction with a directional sort column from the list in the message, e.g. --sort created_at --direction desc for newest first.
If you actually want the manual board order, remove --direction.
Audit scripts for unconditional --direction flags and make them conditional on an explicit --sort.

Example fix

# before
multica issue list --direction desc
# after
multica issue list --sort created_at --direction desc

Defensive patterns

Strategy: validation

Validate before calling

# direction only makes sense with a directional sort column
[ -z "$DIRECTION" ] || { [ -n "$SORT" ] && [ "$SORT" != position ]; } \
  || { echo "--direction needs a non-position --sort" >&2; exit 1; }

Prevention

Never pass --direction unconditionally; pair it with an explicit --sort.
For newest-first use --sort created_at --direction desc instead of relying on defaults.

When it happens

Trigger: Running `multica issue list --direction desc` with no --sort, or `--sort position --direction desc`. Both hit the sortVal == "" || sortVal == "position" branch after the asc/desc check passes.

Common situations: A script that always passes --direction desc for 'newest first' habits, without realizing the default sort is the board position; combining flags copied from two different examples.

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/d9cdfeefae8154ce. Report an issue: GitHub.