{"schemaVersion":"1.0","canonicalUrl":"https://automationtester.in/failures/pytest-unknown-mark","slug":"pytest-unknown-mark","title":"pytest mark not registered","searchTitle":"pytest: not found in markers option","signature":"'smoke' not found in `markers` configuration option","description":"'smoke' not found in `markers` configuration option: pytest is in strict mode and the mark is unregistered, or registered in a config file pytest ignores.","frameworks":["pytest","CI"],"classification":"dependency","summary":"A test uses a custom mark pytest does not know. Without strict markers that is only a PytestUnknownMarkWarning; with strict markers on, collection of that file fails and nothing in it runs.","repro":{"versions":["pytest 9.1.1","pytest-xdist 3.8.0 (installed, for the plugin cause)","Python 3.11.14"],"files":[{"path":"test_checkout.py","language":"python","code":"import pytest\n\n\n@pytest.mark.smoke\ndef test_checkout_total():\n    assert 2 + 2 == 4"}],"command":"python -m pytest -q --strict-markers","output":"______________________ ERROR collecting test_checkout.py _______________________\n'smoke' not found in `markers` configuration option\n=========================== short test summary info ============================\nERROR test_checkout.py - Failed: 'smoke' not found in `markers` configuration...\n!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!\n1 error in 0.04s\n\n# Without --strict-markers the same file prints 1 passed, 1 warning, with:\ntest_checkout.py:4: PytestUnknownMarkWarning: Unknown pytest.mark.smoke - is this a typo?  You can register custom marks to avoid this warning - for details, see https://docs.pytest.org/en/stable/how-to/mark.html","ran":"locally","ranOn":"2026-10-23"},"causes":[{"title":"The mark was never registered","explanation":"Custom marks have to be listed in the markers option or added in a pytest_configure hook. Strictness can come from --strict-markers, from strict_markers in config, or from the pytest 9 strict option, which turns strict_markers on along with three other checks. A pytest.ini containing only strict = true failed the repro the same way.","diagnostic":"Run `pytest --markers` and look for the name. Then search the config and CI command for strict, strict_markers and --strict-markers.","fix":"Register the mark with a one-line description in the config file pytest actually reads."},{"title":"The mark is registered in a file pytest is not reading","explanation":"pytest uses exactly one config file, and pytest.ini wins over pyproject.toml even when it is empty. We registered smoke in pyproject.toml, then added an empty pytest.ini: the run failed again, and the header said configfile: pytest.ini (WARNING: ignoring pytest config in pyproject.toml!).","diagnostic":"Read the configfile: line in the session header of the failing run, locally and in CI. A different rootdir (running pytest from another directory) changes which file is found.","fix":"Keep one pytest config file, delete the stray one, and run pytest from the repository root in CI."},{"title":"A plugin that registers the mark is not loaded","explanation":"Plugins register their own marks when they load. With pytest-xdist installed, @pytest.mark.xdist_group passed under --strict-markers; with -p no:xdist the same file failed with 'xdist_group' not found in `markers` configuration option.","diagnostic":"Check the plugins: line in the session header against the plugin that owns the mark, and compare the CI dependency lock with your local environment.","fix":"Install the plugin in the CI test environment. Do not register the plugin's mark yourself; that would hide the missing plugin."}],"verifiedFix":{"summary":"Register the mark in the config file pytest reports in its header.","files":[{"path":"pytest.ini","language":"ini","code":"[pytest]\nmarkers =\n    smoke: fast checks that gate every pull request"}],"evidence":"Re-run on 2026-10-23 with pytest 9.1.1 on Python 3.11.14: after adding that pytest.ini, `pytest --strict-markers` printed 1 passed and its header read configfile: pytest.ini. The summary line of the failing run is cut at the terminal width, so the full markers text is on the line under the ERROR collecting banner."},"notTheCause":[{"title":"A misspelt parametrize","explanation":"pytest catches that one separately: @pytest.mark.parameterize fails with Unknown 'parameterize' mark, did you mean 'parametrize'? Registering a parameterize marker would silence the real bug."},{"title":"Warnings promoted to errors","explanation":"With -W error::pytest.PytestUnknownMarkWarning the failure is a traceback ending in the warning text, not the markers message. The fix is still registration, but the strict setting to look for is the filterwarnings option."},{"title":"The test itself","explanation":"The error is raised while the module is collected, before any test runs. Nothing inside the test body matters."}],"prevention":["Turn on strict markers in the shared config so a typo fails locally, not only in CI.","Keep a single pytest config file and review any new one in code review.","Lock test plugins in the same dependency group CI installs."],"related":["pytest-fixture-not-found","pytest-import-file-mismatch","pytest-xdist-different-tests-collected"],"references":[{"label":"pytest: how to mark test functions, registering marks","url":"https://docs.pytest.org/en/stable/how-to/mark.html"},{"label":"pytest: configuration file precedence","url":"https://docs.pytest.org/en/stable/reference/customize.html"},{"label":"pytest reference: markers, strict_markers and strict","url":"https://docs.pytest.org/en/stable/reference/reference.html"}],"publishedAt":"2026-10-22","updatedAt":"2026-10-23"}