langchain-ai/deepagents · critical · ValueError

MODE_PREFIXES and MODE_DISPLAY_GLYPHS have mismatched keys:

Error message

MODE_PREFIXES and MODE_DISPLAY_GLYPHS have mismatched keys: only in PREFIXES={_only_prefixes}, only in GLYPHS={_only_glyphs}

What it means

At import time, config.py verifies that MODE_PREFIXES and MODE_DISPLAY_GLYPHS define exactly the same mode keys, raising ValueError on any difference. This is an internal consistency check guarding the developer-mode UI: every mode prefix must have a display glyph and vice versa.

Source

Thrown at libs/code/deepagents_code/config.py:1480

    "command": "/",
}
"""Maps each non-normal mode to its trigger character."""

MODE_DISPLAY_GLYPHS: dict[str, str] = {
    "shell_incognito": "$",
    "shell": "$",
    "command": "/",
}
"""Maps each non-normal mode to its display glyph shown in the prompt/UI."""

if MODE_PREFIXES.keys() != MODE_DISPLAY_GLYPHS.keys():
    _only_prefixes = MODE_PREFIXES.keys() - MODE_DISPLAY_GLYPHS.keys()
    _only_glyphs = MODE_DISPLAY_GLYPHS.keys() - MODE_PREFIXES.keys()
    msg = (
        "MODE_PREFIXES and MODE_DISPLAY_GLYPHS have mismatched keys: "
        f"only in PREFIXES={_only_prefixes}, only in GLYPHS={_only_glyphs}"
    )
    raise ValueError(msg)

_MODE_PREFIXES_BY_LENGTH: tuple[tuple[str, str], ...] = tuple(
    sorted(MODE_PREFIXES.items(), key=lambda item: len(item[1]), reverse=True)
)
"""Mode entries ordered longest-prefix-first.

Pre-sorted at import so `detect_mode_prefix` runs in constant time per
keystroke without re-sorting.
"""


def detect_mode_prefix(text: str) -> tuple[str, str] | None:
    """Return the longest mode prefix and mode for `text`, if any.

    Longer prefixes win so multi-character triggers like `!!` are matched
    before their single-character prefixes (`!`).

    Args:

View on GitHub (pinned to a1af029e6e)

Solutions

Add the missing key to the other mapping so both dicts share the identical key set.
If the mode was removed, delete its entry from both MODE_PREFIXES and MODE_DISPLAY_GLYPHS.
If you see this after an upgrade without local edits, report it as a release bug and pin the previous version.

Example fix

// before
MODE_PREFIXES = {"plan": "plan", "code": "code", "review": "review"}
MODE_DISPLAY_GLYPHS = {"plan": "*", "code": ">"}  # 'review' missing
// after
MODE_DISPLAY_GLYPHS = {"plan": "*", "code": ">", "review": "~"}

Defensive patterns

Strategy: validation

Validate before calling

# run in tests
def assert_mode_maps_consistent(prefixes: dict, glyphs: dict) -> None:
    assert prefixes.keys() == glyphs.keys(), prefixes.keys() ^ glyphs.keys()

Try / catch

try:
    import deepagents_code.config as config
except ValueError as e:
    raise RuntimeError("mode mappings out of sync; check MODE_PREFIXES vs MODE_DISPLAY_GLYPHS") from e

Prevention

When adding/removing a mode, update both MODE_PREFIXES and MODE_DISPLAY_GLYPHS in the same commit
Add a unit test asserting the two key sets are equal
Resolve merge conflicts in config.py by checking both mappings, not just one

When it happens

Trigger: Adding an entry to MODE_PREFIXES (or MODE_DISPLAY_GLYPHS) without the matching entry in the other dict, renaming a mode key in only one, or editing a fork/patch of config.py asymmetrically.

Common situations: Contributing a new agent mode to the coding agent and forgetting the glyph, a merge conflict resolved in only one dict, or a plugin monkeypatching one mapping at import time.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/1e331628ae3adf2a. Report an issue: GitHub.