Skip to content

Improve error message for custom mode not found during CLI initialization #4600

@kiloconnect

Description

@kiloconnect

Description

When the CLI initializes and cannot find a custom mode, it displays a misleading error message saying the mode "is not valid". This error is spurious because the mode itself may be valid, it's just not available in the CLI's expected location.

Symptom

When starting the CLI with a custom mode that isn't found, users see:

Error: Invalid mode "<mode-name>". Valid modes are: <list>

This happens even when:

  • The mode is defined correctly in a project-level .kilocodemodes file
  • The mode works correctly in VS Code
  • The mode is valid but just not in the global location

Root Cause

The CLI initialization code in cli/src/index.ts:71-73 validates modes after loading custom modes from:

  1. Global location: ~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml (Linux)
  2. Project location: <workspace>/.kilocodemodes

However, the error message doesn't distinguish between:

  • A mode that doesn't exist at all (truly invalid)
  • A mode that exists but wasn't found in the expected locations

Expected Behavior

The error message should be more helpful and indicate:

  • Where the CLI looked for custom modes
  • That the mode wasn't found in those locations (rather than saying it's "not valid")
  • Suggestions for where to define custom modes

Suggested Improvement

Change the error message from:

Error: Invalid mode "<mode-name>". Valid modes are: <list>

To something like:

Error: Mode "<mode-name>" not found. 

The CLI looks for custom modes in:
  - Global: ~/.config/Code/User/globalStorage/kilocode.kilo-code/settings/custom_modes.yaml
  - Project: <workspace>/.kilocodemodes

Available modes: <list>

Related Issues

Additional Context

This is particularly confusing for users who have custom modes working in VS Code but not in the CLI, as the error suggests the mode definition itself is invalid rather than just not being found in the CLI's search paths.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Status

    Intake

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions