Yeachan-Heo/oh-my-codex · error · UltragoalError

Invalid --kind: ${raw}. Expected one of ${Array.from(STEERIN

Error message

Invalid --kind: ${raw}. Expected one of ${Array.from(STEERING_KINDS).join(', ')}.

What it means

--kind was provided but is not a member of ULTRAGOAL_STEERING_MUTATION_KINDS. The message helpfully lists every accepted value, so compare your spelling against it.

Source

Thrown at src/cli/ultragoal.ts:224

    ? readRoleRoutingMarker(scope.baseStateDir, { cwd: scope.cwd, sessionId: scope.sessionId })
    : null;
  return resolveNativeSubagentSupportStatus({
    persistedSupportBlocker,
    persistedRoleRoutingMarker,
    persistedCapacityBlocker,
    cwd: scope.cwd,
    sessionId: scope.sessionId,
  });
}

const STEERING_KINDS = new Set<UltragoalSteeringMutationKind>(ULTRAGOAL_STEERING_MUTATION_KINDS);
const STEERING_SOURCES = new Set<UltragoalSteeringSource>(ULTRAGOAL_STEERING_SOURCES);

type CliSteerResult = Awaited<ReturnType<typeof steerUltragoal>>;

function parseSteeringKind(raw: string | undefined): UltragoalSteeringMutationKind {
  if (!raw) throw new UltragoalError('Missing --kind for structured ultragoal steer.');
  if (!STEERING_KINDS.has(raw as UltragoalSteeringMutationKind)) throw new UltragoalError(`Invalid --kind: ${raw}. Expected one of ${Array.from(STEERING_KINDS).join(', ')}.`);
  return raw as UltragoalSteeringMutationKind;
}

function parseSteeringSource(raw: string | undefined, fallback: UltragoalSteeringSource = 'cli'): UltragoalSteeringSource {
  if (!raw) return fallback;
  if (!STEERING_SOURCES.has(raw as UltragoalSteeringSource)) throw new UltragoalError(`Invalid --source: ${raw}. Expected one of ${Array.from(STEERING_SOURCES).join(', ')}.`);
  return raw as UltragoalSteeringSource;
}

function assertPlainObject(value: unknown, label: string): Record<string, unknown> {
  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new UltragoalError(`${label} must be a JSON object.`);
  return value as Record<string, unknown>;
}

function normalizeTargetGoalId(raw: Record<string, unknown>): string | undefined {
  if (typeof raw.targetGoalId === 'string' && raw.targetGoalId.trim()) return raw.targetGoalId.trim();
  if (Array.isArray(raw.targetGoalIds)) return raw.targetGoalIds.find((id): id is string => typeof id === 'string' && id.trim().length > 0)?.trim();
  return undefined;

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Re-run and copy one of the exact values listed in the error message itself
Check the current ULTRAGOAL_STEERING_MUTATION_KINDS export (or --help) for your installed version
Update the package if docs mention a kind your version rejects

Example fix

# before
omx ultragoal steer --kind pause --evidence e --rationale r
# Error: Invalid --kind: pause. Expected one of add_goal, update_goal, ...

# after
omx ultragoal steer --kind update_goal --evidence e --rationale r --goal-id g1 --status paused

Defensive patterns

Strategy: type-guard

Validate before calling

const KINDS = new Set(ULTRAGOAL_STEERING_MUTATION_KINDS as readonly string[]);
if (!KINDS.has(kind)) { console.error(`kind must be one of: ${[...KINDS].join(', ')}`); process.exit(2); }

Type guard

function isValidSteeringKind(v: string, valid: ReadonlySet<string>): v is (typeof ULTRAGOAL_STEERING_MUTATION_KINDS)[number] {
  return valid.has(v);
}

Prevention

Copy enum values from the error text or the exported ULTRAGOAL_STEERING_MUTATION_KINDS constant
Re-validate enums after package upgrades

When it happens

Trigger: Passing e.g. `--kind pause` or `--kind Add_Goal` (wrong casing/snake form) to `omx ultragoal steer` when the accepted set is things like add_goal/update_goal/record_blocker per the engine's enum.

Common situations: Version drift: the enum gained/renamed kinds between releases; guessing kind names from the directive schema; locale casing issues from scripted input.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/741075e00a5b184d. Report an issue: GitHub.