Override file '${overrideId}' not found, using parent mode '

Error message

Override file '${overrideId}' not found, using parent mode '${parentId}' only

What it means

After the parent mode loads, ModeManager reads the override fragment with loadModeFile(overrideId). This warning (Error branch) fires when that call throws — override file missing, unreadable, or invalid JSON — and the manager returns the parent mode unchanged, dropping all override customizations. The active mode is the plain parent, so behavior differs from what the mode author intended.

Source

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

    let parentMode: ModeConfig;
    try {
      parentMode = this.loadMode(parentId);
    } catch (error) {
      if (error instanceof Error) {
        logger.warn('WORKER', `Parent mode '${parentId}' not found for ${modeId}, falling back to 'code'`, { message: error.message });
      } else {
        logger.warn('WORKER', `Parent mode '${parentId}' not found for ${modeId}, falling back to 'code'`, { error: String(error) });
      }
      parentMode = this.loadMode('code');
    }

    let overrideConfig: Partial<ModeConfig>;
    try {
      overrideConfig = this.loadModeFile(overrideId);
      logger.debug('SYSTEM', `Loaded override file: ${overrideId} for parent ${parentId}`);
    } catch (error) {
      if (error instanceof Error) {
        logger.warn('WORKER', `Override file '${overrideId}' not found, using parent mode '${parentId}' only`, { message: error.message });
      } else {
        logger.warn('WORKER', `Override file '${overrideId}' not found, using parent mode '${parentId}' only`, { error: String(error) });
      }
      this.activeMode = parentMode;
      return parentMode;
    }

    if (!overrideConfig) {
      logger.warn('SYSTEM', `Invalid override file: ${overrideId}, using parent mode '${parentId}' only`);
      this.activeMode = parentMode;
      return parentMode;
    }

    const mergedMode = this.deepMerge(parentMode, overrideConfig);
    this.activeMode = mergedMode;
    this.activeModeId = modeId;

    logger.debug('SYSTEM', `Loaded mode with inheritance: ${mergedMode.name} (${modeId} = ${parentId} + ${overrideId})`, undefined, {

View on GitHub (pinned to e2d1df569a)

Solutions

Verify inheritance.overrideId in the mode config resolves to an existing, readable override file.
Recreate or restore the override file with valid JSON and the expected naming.
If overrides are no longer wanted, remove the inheritance block so the mode is standalone and the warning stops.
Inspect error.message in the log entry to distinguish ENOENT (missing file) from a parse error (malformed content).

Example fix

// before: inheritance references a file that does not exist
{ "inheritance": { "parentId": "code", "overrideId": "my-overide" } }
// after: overrideId matches the actual file my-override.json
{ "inheritance": { "parentId": "code", "overrideId": "my-override" } }

Defensive patterns

Strategy: validation

Validate before calling

// confirm the override file exists and parses before activating the mode
const { overrideId } = cfg.inheritance;
const p = modeFilePath(overrideId);
if (!existsSync(p)) throw new Error(`override file missing: ${p}`);
JSON.parse(readFileSync(p, 'utf-8')); // throws early with a clear cause
modeManager.setMode(modeId);

Try / catch

try {
  modeManager.setMode(modeId);
} catch (e) {
  // fallback value is intentional: verify the active mode afterwards
  const active = modeManager.getActiveMode();
  if (active.id !== modeId) log.warn('mode fell back', { modeId, active: active.id });
}

Prevention

Name override files exactly as the overrideId string plus the expected extension.
Include override files in the same package/repo as the modes that reference them.
Avoid cloud-sync placeholders in the modes directory.

When it happens

Trigger: A mode declaring inheritance.overrideId whose override file is absent from the modes directory, has a filename/extension mismatch, contains JSON that fails parsing, or is unreadable (EACCES).

Common situations: Renaming or deleting an override fragment without updating the child mode; shipping a mode that references an override file never packaged; sync tools (OneDrive/Dropbox) leaving placeholder files that fail to read; wrong file extension.

Related errors

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/03d81c7f4aa84541. Report an issue: GitHub.