nautechsystems/nautilus_trader · error · ValueError

Colors dict missing required keys

Error message

Colors dict missing required keys: {missing_keys}. Required keys: {required_keys}

What it means

register_theme requires the colors dict to contain all six mandatory color keys: primary, positive, negative, neutral, background, grid. Missing keys are reported as a set in the ValueError, since downstream plotly templates index these colors directly.

Solutions

  1. Add every required key: primary, positive, negative, neutral, background, grid
  2. Merge a complete default palette with your overrides: colors = {**defaults, **overrides}
  3. Check key spellings against the error's missing_keys list

Example fix

// before
register_theme("custom", template, colors={"primary": "blue", "positive": "green"})  # missing keys
// after
register_theme("custom", template, colors={"primary": "blue", "positive": "green", "negative": "red", "neutral": "gray", "background": "white", "grid": "#ddd"})
Defensive patterns

Strategy: validation

Validate before calling

REQUIRED_COLOR_KEYS = {"primary", "positive", "negative", "neutral", "background", "grid"}
assert REQUIRED_COLOR_KEYS <= set(colors.keys()), REQUIRED_COLOR_KEYS - set(colors)

Type guard

def has_required_colors(colors: dict) -> bool:
    return {"primary", "positive", "negative", "neutral", "background", "grid"} <= set(colors.keys())

Try / catch

try:
    register_theme(name, template, colors)
except ValueError as e:
    if "missing required keys" in str(e):
        colors = {**default_palette, **colors}
        register_theme(name, template, colors)
    else:
        raise

Prevention

When it happens

Trigger: register_theme(name, template, colors={"primary": "#...", "positive": "#..."}) with one or more of the required keys absent.

Common situations: Hand-writing a partial custom theme; migrating themes from another library with a different color schema; typos in key names (e.g. 'bg' instead of 'background').

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors


AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/6803ba01e55dbf38. Report an issue: GitHub.

Appendix: source

Thrown at python/nautilus_trader/analysis/themes.py:178

    ...         "negative": "#ff0000",
    ...         "neutral": "#808080",
    ...         "background": "#ffffff",
    ...         "grid": "#dddddd",
    ...     },
    ... )

    """
    _require_not_none(name, "name")
    _require_not_none(template, "template")
    _require_not_none(colors, "colors")

    if not name.strip():
        raise ValueError("Theme name cannot be empty")

    required_keys = {"primary", "positive", "negative", "neutral", "background", "grid"}
    missing_keys = required_keys - set(colors.keys())
    if missing_keys:
        raise ValueError(
            f"Colors dict missing required keys: {missing_keys}. Required keys: {required_keys}",
        )

    _THEMES[name] = {
        "template": template,
        "colors": colors.copy(),
    }


def list_themes() -> list[str]:
    """
    List all registered theme names.

    Returns
    -------
    list[str]
        List of available theme names.

View on GitHub (pinned to 18893faf8b)