thedotmack/claude-mem · error

Invalid mode ID: ${modeId}

Error message

Invalid mode ID: ${modeId}

What it means

Thrown by ModeManager.loadModeFile() when the mode id fails the MODE_ID_PATTERN regex (/^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$/). This rejects uppercase, special characters, leading/trailing dashes, or any character outside lowercase alphanumeric and single-hyphen segments.

Source

Thrown at src/services/domain/ModeManager.ts:87

    const result = { ...base } as T;

    for (const key in override) {
      const overrideValue = override[key];
      const baseValue = base[key];

      if (this.isPlainObject(overrideValue) && this.isPlainObject(baseValue)) {
        result[key] = this.deepMerge(baseValue, overrideValue as any);
      } else {
        result[key] = overrideValue as T[Extract<keyof T, string>];
      }
    }

    return result;
  }

  private loadModeFile(modeId: string): ModeConfig {
    if (!MODE_ID_PATTERN.test(modeId)) {
      throw new Error(`Invalid mode ID: ${modeId}`);
    }

    const modePath = this.modeDirs
      .map(modesDir => join(modesDir, `${modeId}.json`))
      .find(candidate => existsSync(candidate));

    if (!modePath) {
      throw new Error(`Mode file not found: ${modeId}.json (searched: ${this.modeDirs.join(', ')})`);
    }

    const jsonContent = readFileSync(modePath, 'utf-8');
    return JSON.parse(jsonContent) as ModeConfig;
  }

  loadMode(modeId: string): ModeConfig {
    const inheritance = this.parseInheritance(modeId);

    if (!inheritance.hasParent) {

View on GitHub (pinned to d768ba3643)

Solutions

1. Rename the mode id to lowercase alphanumeric with single hyphens only, e.g. 'code-review'.
2. Rename the corresponding .json file to match, since loadModeFile looks up <modeId>.json.
3. If you need an override, use the double-hyphen form 'parent--override' (both segments still lowercase-alphanumeric-hyphen).

Example fix

// before
manager.loadMode('Code_Review');
// throws 'Invalid mode ID: Code_Review'

// after — rename file to modes/code-review.json and call
manager.loadMode('code-review');

const MODE_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$/;
if (!MODE_ID_PATTERN.test(modeId)) {
  throw new Error(`Rejecting invalid mode id early: ${modeId}`);
}

function isValidModeId(modeId: string): boolean {
  return /^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$/.test(modeId);
}

When it happens

Trigger: Passing a mode id with uppercase ('Code'), spaces, underscores, slashes, or other punctuation to loadMode()/loadModeFile(). Also a mode id that starts or ends with a dash.

Common situations: User names a custom mode 'Code-Review' (uppercase) or 'code_review' (underscore); a path-style id 'modes/code'; copy-paste introduced a trailing space or dash.

Related errors

• Invalid mode inheritance: ${modeId}. Only one level of inher
• Invalid CLAUDE_MEM_WORKER_PORT in settings.json: missing
• Invalid CLAUDE_MEM_WORKER_PORT in settings.json: ${rawPort}
• Unknown Claude model: ${options.model}. Allowed: ${[...allow
• CLAUDE_MEM_QUEUE_ENGINE is not "bullmq"

AI-assisted analysis of thedotmack/claude-mem@d768ba3643 (2026-08-12). Data as JSON: /api/errors/22aa6106d98f2a82. Report an issue: GitHub.