jackwener/OpenCLI · error · ArgumentError

--trace must be one of: off, on, retain-on-failure. Received

Error message

--trace must be one of: off, on, retain-on-failure. Received: "${String(raw)}"

What it means

normalizeTraceMode validates the --trace option, allowing only 'off', 'on', or 'retain-on-failure' (empty/undefined maps to 'off'). Any other value raises an ArgumentError naming the accepted values and the offending input. Playwright-style trace collection is therefore strictly enum-validated before execution.

Source

Thrown at src/execution.ts:51

import { clearDaemonRunContext, generateRunId, isUnknownOutcomeError, releaseSiteSessionLease, setDaemonCommandTimeoutSeconds, setDaemonRunContext } from './browser/daemon-client.js';
import { emitHook, type HookContext } from './hooks.js';
import { log } from './logger.js';
import { isElectronApp } from './electron-apps.js';
import { probeCDP, resolveElectronEndpoint } from './launcher.js';
import { ObservationSession, exportObservationSession, type ObservationExportResult, type ObservationExportStatus } from './observation/index.js';
import { resolveAdapterSourcePath } from './adapter-source.js';

const _loadedModules = new Map<string, Promise<void>>();
/** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
const _moduleMtimes = new Map<string, number>();
const _userClisDir = `${os.homedir()}/.opencli/clis/`;

type TraceMode = 'off' | 'on' | 'retain-on-failure';

function normalizeTraceMode(raw: unknown): TraceMode {
  if (raw === undefined || raw === null || raw === '' || raw === 'off') return 'off';
  if (raw === 'on' || raw === 'retain-on-failure') return raw;
  throw new ArgumentError(`--trace must be one of: off, on, retain-on-failure. Received: "${String(raw)}"`);
}

export function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs {
  const result: CommandArgs = { ...kwargs };

  for (const argDef of cmdArgs) {
    const val = result[argDef.name];

    if (argDef.required && (val === undefined || val === null || val === '')) {
      throw new ArgumentError(
        `Argument "${argDef.name}" is required.`,
        argDef.help ?? `Provide a value for --${argDef.name}`,
      );
    }

    if (val !== undefined && val !== null) {
      if (argDef.type === 'int' || argDef.type === 'number') {
        const num = Number(val);

View on GitHub (pinned to 49907e53dc)

Solutions

Use exactly one of: off, on, retain-on-failure (lowercase).
Omit --trace to default to off.
Fix config/CI files that interpolate a non-enum value into the trace option.

Example fix

// before
{ trace: 'always' }
// after
{ trace: 'retain-on-failure' }

Defensive patterns

Strategy: validation

Validate before calling

const TRACE_MODES = ['off', 'on', 'retain-on-failure'] as const;
if (opts.trace !== undefined && !TRACE_MODES.includes(opts.trace as any)) {
  throw new Error(`--trace must be one of: ${TRACE_MODES.join(', ')}`);
}

Type guard

type TraceMode = 'off' | 'on' | 'retain-on-failure';
const isTraceMode = (v: unknown): v is TraceMode =>
  v === 'off' || v === 'on' || v === 'retain-on-failure';

Try / catch

try {
  await opencli.run(cmd, { trace: opts.trace });
} catch (e) {
  if (/--trace must be one of/.test(e.message)) {
    console.error('Use --trace off | on | retain-on-failure');
  } else throw e;
}

Prevention

Use the exact lowercase enum strings; never true/false or always.
Omit the flag when you don't need traces (defaults to off).
Centralize the trace value in one config constant validated once.

When it happens

Trigger: Passing --trace true, --trace always, --trace retain, --trace ON (case-sensitive), or --trace 1 through kwargs or CLI flags.

Common situations: Copy-pasting trace flags from other tools (e.g. Playwright's `retain-on-failure` misspelled as retainonfailure); booleans used where an enum string is expected; case-mismatch after editing config files.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/fe9f96c4094dd745. Report an issue: GitHub.