can1357/oh-my-pi · error · Error

Invalid --surface '${raw}'. Valid values: ${GALLERY_SURFACE_

Error message

Invalid --surface '${raw}'. Valid values: ${GALLERY_SURFACE_TOKENS.join(", ")}

What it means

parseGallerySurfaces validates each comma-separated token of the --surface flag against the known GALLERY_SURFACES list (plus the 'all' shorthand). Unknown tokens abort with the raw token and the full list of valid values. Matching is case-insensitive (tokens are trimmed and lowercased), but must still be exact strings from the list.

Source

Thrown at packages/coding-agent/src/cli/gallery-cli.ts:71

export const GALLERY_STATE_TOKENS = Object.keys(GALLERY_STATE_ALIASES);

/** Gallery surfaces in stable product order. */
export const GALLERY_SURFACES = ["tool", "composer", "segment"] as const;
export type GallerySurface = (typeof GALLERY_SURFACES)[number];
export const GALLERY_SURFACE_TOKENS = [...GALLERY_SURFACES, "all"] as const;

/** Expand user-provided surface tokens while preserving product order. */
export function parseGallerySurfaces(surfaces: readonly string[] | undefined): GallerySurface[] | undefined {
	if (!surfaces || surfaces.length === 0) return undefined;
	const requested = new Set<GallerySurface>();
	for (const raw of surfaces) {
		const token = raw.trim().toLowerCase();
		if (token === "all") {
			for (const surface of GALLERY_SURFACES) requested.add(surface);
			continue;
		}
		if (!GALLERY_SURFACES.includes(token as GallerySurface)) {
			throw new Error(`Invalid --surface '${raw}'. Valid values: ${GALLERY_SURFACE_TOKENS.join(", ")}`);
		}
		requested.add(token as GallerySurface);
	}
	return GALLERY_SURFACES.filter(surface => requested.has(surface));
}

/** Normalize user-provided `--state` tokens to the internal gallery lifecycle states. */
export function parseGalleryStates(states: readonly string[] | undefined): GalleryState[] | undefined {
	if (!states || states.length === 0) return undefined;
	const parsed: GalleryState[] = [];
	for (const raw of states) {
		const state = GALLERY_STATE_ALIASES[raw.trim().toLowerCase()];
		if (!state) {
			throw new Error(`Invalid --state '${raw}'. Valid values: ${GALLERY_STATE_TOKENS.join(", ")}`);
		}
		if (!parsed.includes(state)) parsed.push(state);
	}
	return parsed;

View on GitHub (pinned to 9690622007)

Solutions

1. Use only tokens listed in the error's 'Valid values:' part, or 'all' for every surface
2. Copy names exactly from `omp gallery --help`; matching is lowercase and trimmed but must be the exact token
3. Split multi-value flags and test each token if unsure which one is bad
4. If a previously working token broke, check the changelog/help for a renamed surface and update the script

Example fix

// before
omp gallery --surface agents,tools
// after
omp gallery --surface agent,tools   # or --surface all

const GALLERY_SURFACES = ['agent','tools' /* see omp gallery --help for the exact list */];
function assertSurfaces(raw) {
  for (const token of raw.split(',')) {
    const t = token.trim().toLowerCase();
    if (t !== 'all' && !GALLERY_SURFACES.includes(t))
      throw new Error(`Invalid --surface '${token}'. Valid: ${GALLERY_SURFACES.join(', ')}`);
  }
}

type GallerySurface = (typeof GALLERY_SURFACES)[number];
const isGallerySurface = (t: string): t is GallerySurface =>
  (GALLERY_SURFACES as readonly string[]).includes(t);

try {
  parse(['--surface', raw]);
} catch (e) {
  if (/Invalid --surface/.test((e as Error).message)) {
    console.error(`Bad token: ${e.message.match(/'([^']+)'/)?.[1]}. Valid values: ${e.message.match(/Valid values: (.+)$/)?.[1]}`);
  } else throw e;
}

When it happens

Trigger: `omp gallery --surface agentsx`, `--surface tools,agentz` (one bad token fails the whole list), or a surface renamed in a newer version so an old script's token no longer matches.

Common situations: Guessing surface names instead of copying from --help, pluralizing a singular surface name (`--surface agents` when only `agent` exists), or scripts breaking after a surface token was renamed/removed in an update.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid --max-time value: ${JSON.stringify(value)}. Expected
• Invalid --service-tier value: ${JSON.stringify(value)}. Expe
• unknown file type: {value}
• invalid size: {value}
• 2

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/7fc31b08b211a6ab. Report an issue: GitHub.