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

The Cache.mkdir method creates a directory under pytest's cache for storing files across sessions. The name parameter must be a simple name without path separators. If Path(name).parts has more than one element (i.e., contains '/' or '\'), pytest raises ValueError to prevent path traversal and keep the cache layout flat.

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 98b357f69e)

Solutions

1. Use a flat, separator-free name: cache.mkdir('myplugin_data').
2. Namespace the name with a prefix instead of a path: cache.mkdir('myplugin_data').
3. If you need nested storage, manage paths manually under the returned directory.

Example fix

# before
request.config.cache.mkdir('myplugin/output')

# after
request.config.cache.mkdir('myplugin_output')

from pathlib import Path

def safe_cache_mkdir(cache, name: str):
    if len(Path(name).parts) > 1:
        raise ValueError(f"Cache mkdir name must not contain path separators, got: {name!r}")
    return cache.mkdir(name)

from pathlib import Path

def is_flat_cache_name(name: str) -> bool:
    return isinstance(name, str) and len(Path(name).parts) == 1

When it happens

Trigger: Calling request.config.cache.mkdir('subdir/mydir') or cache.mkdir('a/b/c'). Path('subdir/mydir').parts yields ('subdir', 'mydir'), length 2 > 1, so ValueError is raised.

Common situations: Trying to organize cached files into a nested directory hierarchy, or accidentally including an absolute path or leading './' in the name.

Related errors

• absolute tolerance can't be negative: {absolute_tolerance}
• could not create numbered dir with prefix {prefix} in {root}
• cannot create lockfile in {p}
• {optname} must be a filename, given: {path}
• {optname} must be a directory, given: {path}

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/90821d20c3adf395.json. Report an issue: GitHub.