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

fileName must be a string

Error message

fileName must be a string

What it means

validateStateFileName throws when the fileName argument is not a string. FileNames are user-facing state file identifiers joined into state directory paths, so type is checked before any content validation.

Source

Thrown at src/mcp/state-paths.ts:156

  if (normalized.includes('..')) {
    throw new Error('mode must not contain ".."');
  }
  if (normalized.includes('/') || normalized.includes('\\')) {
    throw new Error('mode must not contain path separators');
  }
  if (!STATE_MODE_SEGMENT_PATTERN.test(normalized)) {
    throw new Error('mode must match ^[A-Za-z0-9_-]{1,64}$');
  }
  return normalized;
}

export function getStateFilename(mode: string): string {
  return `${validateStateModeSegment(mode)}${STATE_FILE_SUFFIX}`;
}

export function validateStateFileName(fileName: unknown): string {
  if (typeof fileName !== 'string') {
    throw new Error('fileName must be a string');
  }
  const normalized = fileName.trim();
  if (!normalized) {
    throw new Error('fileName must be a non-empty string');
  }
  if (normalized.includes('..')) {
    throw new Error('fileName must not contain ".."');
  }
  if (normalized.includes('/') || normalized.includes('\\')) {
    throw new Error('fileName must not contain path separators');
  }
  if (!STATE_FILE_NAME_PATTERN.test(normalized)) {
    throw new Error('fileName must match ^[A-Za-z0-9._-]{1,128}$');
  }
  return normalized;
}

function convertWindowsToWslPath(raw: string): string {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Coerce with String(fileName) at the call site
2. Default it: fileName ?? defaultStateFileName
3. Add a runtime type guard in your client wrapper

Example fix

// before
getStateFilePath(123);
// after
getStateFilePath(String(123));

if (typeof fileName !== 'string') fileName = String(fileName);

function isFileNameInput(v: unknown): v is string { return typeof v === 'string'; }

When it happens

Trigger: fileName: 123, fileName: true, fileName: ["state.json"], or undefined passed explicitly.

Common situations: Untyped JSON config; programmatic callers passing Path objects or file handles; destructuring mistakes leaving fileName undefined.

Understand the failure class

Background: "Wrong argument type", "must be a string", "expected Array or Prism::Scope": TypeError and ArgumentError when a library receives a value of the wrong type — this error's family across 28 libraries.

Related errors

• mode must be a string
• ${name} must be a string
• session_id must be a string
• mode must be a non-empty string
• mode must not contain ".."

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