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

Raised by TerminalWriter._get_pygments_formatter() when PYTEST_THEME_MODE is not 'dark' or 'light', causing pygments.util.OptionError on the TerminalFormatter's bg parameter. pytest surfaces this as UsageError with the allowed values. The default is 'dark' when the variable is unset.

Solutions

1. Set PYTEST_THEME_MODE to exactly 'dark' or 'light'.
2. Unset the variable to accept the 'dark' default.
3. Check shell quoting and case.

Example fix

# before
export PYTEST_THEME_MODE=Dark
# after
export PYTEST_THEME_MODE=dark

import os
mode = os.getenv('PYTEST_THEME_MODE', 'dark')
if mode not in ('dark', 'light'):
    os.environ['PYTEST_THEME_MODE'] = 'dark'

def is_valid_theme_mode(v: str) -> bool:
    return v in ('dark', 'light')

When it happens

Trigger: Setting PYTEST_THEME_MODE=Dark (wrong case), PYTEST_THEME_MODE=black, or any value other than 'dark'/'light'.

Common situations: Case sensitivity mistakes; copy-paste from documentation with smart quotes; setting the value to match a terminal scheme name rather than the two allowed literals.

Related errors

• PYTEST_THEME environment variable has an invalid value
• alias conflicts with existing configuration option
• is already an alias of
• Blocking conftest files using -p is not supported: -p no
• is not a Warning subclass

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/e9af25b6a063d654. Report an issue: GitHub.

Appendix: 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 0d6fbdeffa)