pytest-dev/pytest · error · UsageError

PYTEST_THEME_MODE environment variable has an invalid value:

Error message

PYTEST_THEME_MODE environment variable has an invalid value: '{theme_mode}'. The allowed values are 'dark' (default) and 'light'.

What it means

Pytest uses PYTEST_THEME_MODE to set the background mode ('dark' or 'light') for syntax highlighting in tracebacks. If the value is anything other than 'dark' or 'light', pygments raises OptionError, which pytest wraps as a UsageError. The default is 'dark' when the variable is unset.

Source

Thrown at src/_pytest/_io/terminalwriter.py:230

            return DiffLexer()
        else:
            assert_never(lexer)

    def _get_pygments_formatter(self) -> TerminalFormatter:
        from _pytest.config.exceptions import UsageError

        theme = os.getenv("PYTEST_THEME")
        theme_mode = os.getenv("PYTEST_THEME_MODE", "dark")

        try:
            return TerminalFormatter(bg=theme_mode, style=theme)
        except pygments.util.ClassNotFound as e:
            raise UsageError(
                f"PYTEST_THEME environment variable has an invalid value: '{theme}'. "
                "Hint: See available pygments styles with `pygmentize -L styles`."
            ) from e
        except pygments.util.OptionError as e:
            raise UsageError(
                f"PYTEST_THEME_MODE environment variable has an invalid value: '{theme_mode}'. "
                "The allowed values are 'dark' (default) and 'light'."
            ) from e

    def _highlight(
        self, source: str, lexer: Literal["diff", "python"] = "python"
    ) -> str:
        """Highlight the given source if we have markup support."""
        if not source or not self.hasmarkup or not self.code_highlight:
            return source

        pygments_lexer = self._get_pygments_lexer(lexer)
        pygments_formatter = self._get_pygments_formatter()

        highlighted: str = pygments.highlight(
            source, pygments_lexer, pygments_formatter
        )
        # pygments terminal formatter may add a newline when there wasn't one.

View on GitHub (pinned to 98b357f69e)

Solutions

1. Set PYTEST_THEME_MODE to either 'dark' or 'light'.
2. Unset PYTEST_THEME_MODE to use the default 'dark'.
3. Trim any whitespace or quotes from the env var value.

Example fix

# before
export PYTEST_THEME_MODE=night

# after
export PYTEST_THEME_MODE=dark

import os

theme_mode = os.getenv('PYTEST_THEME_MODE', 'dark')
if theme_mode not in ('dark', 'light'):
    raise ValueError(f"PYTEST_THEME_MODE='{theme_mode}' is invalid. Allowed: 'dark', 'light'")

When it happens

Trigger: Setting PYTEST_THEME_MODE to an invalid value such as 'blue', 'night', 'auto', or 'True'. The error fires in _get_pygments_formatter() when TerminalFormatter(bg=theme_mode, style=theme) rejects the bg argument.

Common situations: Users guessing allowed values, copying a value from a different tool's theme config (e.g., a terminal emulator), or including surrounding whitespace/quotes in the env var.

Related errors

• PYTEST_THEME environment variable has an invalid value: '{th
• {optname} must be a filename, given: {path}
• {optname} must be a directory, given: {path}
• plugin {name} cannot be disabled
• Blocking conftest files using -p is not supported: -p no:{na

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/e9af25b6a063d654.json. Report an issue: GitHub.