{"id":"73c7ef41b5b4d649","repo":"pytest-dev/pytest","slug":"optname-must-be-a-filename-given-path","errorCode":null,"errorMessage":"{optname} must be a filename, given: {path}","messagePattern":"(.+?) must be a filename, given: (.+?)","errorType":"validation","errorClass":"UsageError","httpStatus":null,"severity":"error","filePath":"src/_pytest/config/__init__.py","lineNumber":297,"sourceCode":"\n    from _pytest.deprecated import CONSOLE_MAIN\n\n    warnings.warn(CONSOLE_MAIN, stacklevel=2)\n    return _console_main()\n\n\nclass cmdline:  # compatibility namespace\n    main = staticmethod(main)\n\n\ndef filename_arg(path: str, optname: str) -> str:\n    \"\"\"Argparse type validator for filename arguments.\n\n    :path: Path of filename.\n    :optname: Name of the option.\n    \"\"\"\n    if os.path.isdir(path):\n        raise UsageError(f\"{optname} must be a filename, given: {path}\")\n    return path\n\n\ndef directory_arg(path: str, optname: str) -> str:\n    \"\"\"Argparse type validator for directory arguments.\n\n    :path: Path of directory.\n    :optname: Name of the option.\n    \"\"\"\n    if not os.path.isdir(path):\n        raise UsageError(f\"{optname} must be a directory, given: {path}\")\n    return path\n\n\n# Plugins that cannot be disabled via \"-p no:X\" currently.\nessential_plugins = (\n    \"mark\",\n    \"main\",","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/pytest-dev/pytest/blob/98b357f69e380da908740a212288d73b2ee06687/src/_pytest/config/__init__.py#L279-L315","documentation":"The filename_arg function is an argparse type validator used by pytest CLI options (e.g., --pdbcls, --override-ini file args) that must receive a file path, not a directory. If the provided path resolves to an existing directory, pytest raises UsageError. This prevents pytest from treating a directory where it expects a file.","triggerScenarios":"Passing a directory path to a pytest CLI option that expects a filename (e.g., a plugin registration or ini-override argument wired through filename_arg). os.path.isdir(path) returns True, triggering the error.","commonSituations":"Pointing an option at a project root or a package directory instead of a specific .py file. Tab-completion accidentally selecting a directory, or a config script computing a path incorrectly.","solutions":["Point the option at a specific file (e.g., myplugin.py) instead of the containing directory.","Verify the path with `ls -la <path>` to confirm it is a file, not a directory.","Check that any variable or script building the path appends a filename component."],"exampleFix":"# before\npytest -p myplugin_dir/\n\n# after\npytest -p myplugin_dir/myplugin.py","handlingStrategy":"validation","validationCode":"import os\n\ndef ensure_is_filename(path: str, optname: str) -> str:\n    if os.path.isdir(path):\n        raise ValueError(f\"{optname} must be a filename, but '{path}' is a directory\")\n    if not os.path.isfile(path):\n        raise FileNotFoundError(f\"{optname}='{path}' does not exist or is not a file\")\n    return path","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify paths with os.path.isfile() before passing to pytest options that expect filenames.","Use absolute paths to avoid ambiguity with relative directory resolution."],"tags":["config","cli","argparse","filesystem"],"analyzedSha":"98b357f69e380da908740a212288d73b2ee06687","analyzedAt":"2026-08-04T20:26:34.442Z","schemaVersion":2}