Mode file not found: .json (searched: )

Error message

Mode file not found: ${modeId}.json (searched: ${this.modeDirs.join(', ')})

What it means

loadModeFile searches each configured mode directory for `<modeId>.json`; if the ID is valid but no candidate file exists on disk, it throws this error listing all searched directories. It means the mode is recognized syntactically but no definition file is installed.

Solutions

Create `<modeId>.json` in one of the listed modeDirs (the error message names them).
Fix the mode name to match an existing file's name (case-sensitive).
Verify modeDirs configuration points at the directory that actually holds your mode files.
Reinstall/rebuild the package so default mode files (e.g. code.json) are present.

Example fix

// before
await modeManager.loadMode('architect'); // no architect.json anywhere
// after
// write ~/.claude-mem/modes/architect.json with a ModeConfig, then:
await modeManager.loadMode('architect');

Defensive patterns

Strategy: fallback

Validate before calling

const dirs = ['/path/to/modes']; // mirror modeDirs config
if (!dirs.some(d => fs.existsSync(path.join(d, `${modeId}.json`)))) throw new Error(`No ${modeId}.json in ${dirs.join(', ')}`);

Try / catch

try { return await manager.loadMode(modeId); } catch (e) { if (e.message.startsWith('Mode file not found')) { logger.warn(`Mode '${modeId}' not installed; using 'code'`); return manager.loadMode('code'); } throw e; }

Prevention

Verify the modes directory is created and populated during install/build.
Name mode files exactly `<modeId>.json`, case-sensitive.
Ship default mode files with the package and exclude them from cleanup.
List available mode files at startup to surface missing definitions early.

When it happens

Trigger: loadMode('xyz') where no modesDir contains xyz.json; modes directory misconfigured/pointing at the wrong path; mode file deleted or never created.

Common situations: Custom mode file placed in the wrong directory; typo in the mode name vs the JSON filename; a plugin/version update moved the modes directory; running from a checkout that lacks the built mode assets.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of thedotmack/claude-mem@d8bc9755e7 (2026-09-17). Data as JSON: /api/errors/6ef5497d2c3df4b2. Report an issue: GitHub.

Appendix: source

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

      } 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) {
      try {
        const mode = this.loadModeFile(modeId);
        this.activeMode = mode;
        this.activeModeId = modeId;
        logger.debug('SYSTEM', `Loaded mode: ${mode.name} (${modeId})`, undefined, {
          types: mode.observation_types.map(t => t.id),
          concepts: mode.observation_concepts.map(c => c.id)
        });

View on GitHub (pinned to d8bc9755e7)