{"record":{"id":"98f4c88266d36623","repo":"pytest-dev/pytest","slug":"tmp-path-retention-count-must-be-0-current-inp","errorCode":null,"errorMessage":"tmp_path_retention_count must be >= 0. Current input: {count}.","messagePattern":"tmp_path_retention_count must be >= 0\\. Current input: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/_pytest/tmpdir.py","lineNumber":97,"sourceCode":"        # Register cleanups for session finish. Also called atexit as a last\n        # resort if sessionfinish for some reason doesn't happen.\n        self._exit_stack = ExitStack()\n\n    @classmethod\n    def from_config(\n        cls,\n        config: Config,\n        *,\n        _ispytest: bool = False,\n    ) -> TempPathFactory:\n        \"\"\"Create a factory according to pytest configuration.\n\n        :meta private:\n        \"\"\"\n        check_ispytest(_ispytest)\n        count = int(config.getini(\"tmp_path_retention_count\"))\n        if count < 0:\n            raise ValueError(\n                f\"tmp_path_retention_count must be >= 0. Current input: {count}.\"\n            )\n\n        policy: RetentionType = config.getini(\"tmp_path_retention_policy\")\n\n        return cls(\n            given_basetemp=config.option.basetemp,\n            trace=config.trace.get(\"tmpdir\"),\n            retention_count=count,\n            retention_policy=policy,\n            _ispytest=True,\n        )\n\n    def _ensure_relative_to_basetemp(self, basename: str) -> str:\n        basename = os.path.normpath(basename)\n        if (self.getbasetemp() / basename).resolve().parent != self.getbasetemp():\n            raise ValueError(f\"{basename} is not a normalized and relative path\")\n        return basename","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/pytest-dev/pytest/blob/0d6fbdeffa57c796123f62f81f7dd370d9b7ecdc/src/_pytest/tmpdir.py#L79-L115","documentation":"TempPathFactory.from_config() reads the ini option tmp_path_retention_count, coerces it to int, and rejects negatives. The count governs how many past basetemp directories pytest keeps around between runs; zero is valid (keep none) but a negative value is meaningless, so it fails fast during session configuration rather than later producing an empty cleanup loop.","triggerScenarios":"Setting `tmp_path_retention_count = -1` (or any negative) in pyproject.toml [tool.pytest.ini_options], pytest.ini, tox.ini, or setup.cfg [pytest]. The error fires at session start, before any test runs.","commonSituations":"Typo (e.g. `-1` instead of `1`); copy-paste from a docs example that used 0; misunderstanding the option as 'keep last N including future' and using a sentinel; migrating from keep_env or older tmpdir options.","solutions":["Set tmp_path_retention_count to 0 or a positive integer (0 = purge all old basetemps, default is 3).","If you want minimal disk use, set tmp_path_retention_policy = 'none' or 'all' alongside a non-negative count.","Search all config files pytest loads (pyproject.toml, pytest.ini, tox.ini, setup.cfg) plus -o overrides for the offending value."],"exampleFix":"# before — pyproject.toml\n[tool.pytest.ini_options]\ntmp_path_retention_count = -1\n\n# after\n[tool.pytest.ini_options]\ntmp_path_retention_count = 0","handlingStrategy":"validation","validationCode":"# In conftest.py — validate at session start before TempPathFactory reads it.\nimport pytest\n\ndef pytest_configure(config):\n    count = int(config.getini(\"tmp_path_retention_count\"))\n    if count < 0:\n        raise pytest.UsageError(\n            f\"tmp_path_retention_count must be >= 0, got {count}\"\n        )","typeGuard":"def is_valid_retention_count(value) -> bool:\n    try:\n        return int(value) >= 0\n    except (TypeError, ValueError):\n        return False","tryCatchPattern":"# Config is read before tests run; catching at runtime is too late.\n# Validate in CI with a grep instead:\n#   rg \"tmp_path_retention_count\\\\s*=\\\\s*-[0-9]\" pyproject.toml pytest.ini tox.ini","preventionTips":["Keep tmp_path_retention_count at 0 or above (default is 3).","Add a pre-commit grep for `tmp_path_retention_count = -` to catch typos.","Remember 0 is valid (purge all); you never need a negative value."],"tags":["config","tmp-path","ini","validation"],"backgroundTag":null,"analyzedSha":"0d6fbdeffa57c796123f62f81f7dd370d9b7ecdc","analyzedAt":"2026-08-11T20:52:36.969Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}