Invalid mode inheritance: ${modeId}. Only one level of inher

Error message

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

What it means

Thrown by ModeManager.parseInheritance() when a mode id contains more than one '--' separator. The mode system supports exactly one level of inheritance expressed as 'parent--override'; splitting on '--' must yield at most two parts. Three or more parts (e.g. 'a--b--c') is rejected.

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 d768ba3643)

Solutions

Use a single inheritance level: 'parent--override' only. If you need deeper customization, edit the override JSON to deep-merge what you need rather than chaining.
If you have 'a--b--c', flatten by making a single override file 'a--bplusc' that combines b and c's deltas.
Validate mode ids against the pattern before calling loadMode.

Example fix

// before
manager.loadMode('code--review--strict');
// throws 'Invalid mode inheritance: code--review--strict...'

// after — one level only, with the override JSON merging both deltas
manager.loadMode('code--review');
// where modes/code--review.json contains the merged review+strict overrides

Defensive patterns

Strategy: validation

Validate before calling

function isValidInheritance(modeId: string): boolean {
  return modeId.split('--').length <= 2;
}

Type guard

function isSingleLevelInheritance(modeId: string): boolean {
  return modeId.split('--').length <= 2 && /^[a-z0-9]+(?:-[a-z0-9]+)*(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$/.test(modeId);
}

Prevention

Never chain '--' more than once; edit the override JSON to combine deltas instead.
Validate mode ids against MODE_ID_PATTERN before calling loadMode.
Remember the override id is the whole 'parent--override' string, not a third segment.

When it happens

Trigger: Passing a mode id like 'code--review--strict' to loadMode(); chaining overrides thinking inheritance is transitive; a generated mode id concatenates two override suffixes.

Common situations: User creates a custom override of an override; tooling builds mode ids by joining multiple segments with '--'; misunderstanding that the override is the full 'parent--override' id, not a third segment.

Related errors

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