pytest-dev/pytest · error · ValueError

name is not allowed to contain path separators

Error message

name is not allowed to contain path separators

What it means

Raised by Cache.mkdir() when the supplied name contains a path separator, detected by Path(name) having more than one part. The cache API is designed for flat, single-segment namespaced keys to prevent path traversal and arbitrary directory creation under the cache root. Names must be a single path component.

Solutions

1. Use a single flat name: cache.mkdir('myplugin_subdir').
2. Encode hierarchy in the name with a safe delimiter that is not a path separator (e.g. '__').
3. If you need nested dirs, manage them outside the cache API via pathlib.

Example fix

// before
request.config.cache.mkdir('myplugin/data')
// after
request.config.cache.mkdir('myplugin__data')

from pathlib import Path
def safe_cache_mkdir(cache, name):
    if len(Path(name).parts) > 1:
        name = name.replace('/', '__').replace('\\', '__')
    return cache.mkdir(name)

from pathlib import Path
def is_flat_name(name: str) -> bool:
    return len(Path(name).parts) <= 1

When it happens

Trigger: request.config.cache.mkdir('myplugin/subdir') (contains '/'); cache.mkdir('a\b') on Windows; passing a composite key intended for a hierarchy.

Common situations: Treating the cache key like a filesystem path; attempting to nest cache directories; porting code that joined segments with os.sep.

Related errors

• is not a normalized and relative path
• The temporary directory
• The temporary directory

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

Appendix: source

Thrown at src/_pytest/cacheprovider.py:179

        path.mkdir(exist_ok=True, parents=True)

    def mkdir(self, name: str) -> Path:
        """Return a directory path object with the given name.

        If the directory does not yet exist, it will be created. You can use
        it to manage files to e.g. store/retrieve database dumps across test
        sessions.

        .. versionadded:: 7.0

        :param name:
            Must be a string not containing a ``/`` separator.
            Make sure the name contains your plugin or application
            identifiers to prevent clashes with other cache users.
        """
        path = Path(name)
        if len(path.parts) > 1:
            raise ValueError("name is not allowed to contain path separators")
        res = self._cachedir.joinpath(self._CACHE_PREFIX_DIRS, path)
        self._mkdir(res)
        return res

    def _getvaluepath(self, key: str) -> Path:
        return self._cachedir.joinpath(self._CACHE_PREFIX_VALUES, Path(key))

    def get(self, key: str, default):
        """Return the cached value for the given key.

        If no value was yet cached or the value cannot be read, the specified
        default is returned.

        :param key:
            Must be a ``/`` separated value. Usually the first
            name is the name of your plugin or your application.
        :param default:
            The value to return in case of a cache-miss or invalid cache value.

View on GitHub (pinned to 0d6fbdeffa)