Invalid mode inheritance

Error message

Invalid mode inheritance: ${modeId}. Only one level of inheritance supported (parent--override)

What it means

ModeManager.parseInheritance parses mode IDs of the form `parent--override` to support exactly one level of inheritance. If the mode ID contains more than one `--` separator (3+ parts), it cannot be represented and the manager throws this error. One-level inheritance is a hard design constraint of the mode system.

Solutions

Use a mode ID with at most one `--` separator, e.g. `code--strict`.
Flatten the desired 3-level config into a single override file that already contains the merged settings.
Rename the mode file to remove extra `--` separators.
If deeper inheritance is needed, chain manually: load parent via loadMode and merge yourself.

Example fix

// before
await modeManager.loadMode('architect--strict--v2');
// after
await modeManager.loadMode('architect--strict'); // or merge architect + strict-v2 into one file

Defensive patterns

Strategy: validation

Validate before calling

const parts = modeId.split('--');
if (parts.length > 2) throw new Error(`Mode id '${modeId}' has ${parts.length - 1} inheritance levels; max 1`);

Type guard

const isValidModeId = (id: string): boolean => /^[a-z0-9]+(--[a-z0-9]+)?$/.test(id);

Try / catch

try { await manager.loadMode(modeId); } catch (e) { if (e.message.includes('Invalid mode inheritance')) throw new Error(`Flatten '${modeId}' to parent--override form`); throw e; }

Prevention

Treat `--` as reserved for exactly one inheritance level in mode naming.
Document mode naming conventions for users creating custom modes.
Merge deep chains into a single override file ahead of time.
Validate mode IDs at config-load time, not deep in runtime calls.

When it happens

Trigger: Requesting or loading a mode whose ID contains two or more `--` sequences, e.g. `architect--strict--v2`, typically via loadMode()/mode() with a hand-written mode ID or a mode file named with extra `--`.

Common situations: Users inventing deeper inheritance chains (`a--b--c`) assuming nesting is supported; filenames copied from another project that used multi-level naming; concatenating override suffixes programmatically.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

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

    if (!ModeManager.instance) {
      ModeManager.instance = new ModeManager();
    }
    return ModeManager.instance;
  }

  private parseInheritance(modeId: string): {
    hasParent: boolean;
    parentId: string;
    overrideId: string;
  } {
    const parts = modeId.split('--');

    if (parts.length === 1) {
      return { hasParent: false, parentId: '', overrideId: '' };
    }

    if (parts.length > 2) {
      throw new Error(
        `Invalid mode inheritance: ${modeId}. Only one level of inheritance supported (parent--override)`
      );
    }

    return {
      hasParent: true,
      parentId: parts[0],
      overrideId: modeId 
    };
  }

  private isPlainObject(value: unknown): boolean {
    return (
      value !== null &&
      typeof value === 'object' &&
      !Array.isArray(value)
    );
  }

View on GitHub (pinned to d8bc9755e7)