SeleniumHQ/selenium · error · FileNotFoundError

Storage state file not found: {file_path}

Error message

Storage state file not found: {file_path}

What it means

When `new_context(storage_state=...)` is given a string or pathlib.Path, Selenium treats it as a file path to a JSON storage-state file. If that path does not exist, it raises `FileNotFoundError`. The storage state file holds cookies (and optionally origins) to pre-seed the request context.

Source

Thrown at py/selenium/webdriver/common/api_request_context.py:566

        fail_on_status_code: bool = False,
    ) -> "_IsolatedAPIRequestContext":
        """Create an isolated API request context that does not sync with the browser.

        Args:
            base_url: Optional base URL for this context.
            extra_headers: Optional headers for this context.
            storage_state: Optional cookies to pre-load, as a dict, JSON file path, or Path.
            fail_on_status_code: If True, raise APIRequestFailure for non-2xx responses.

        Returns:
            An _IsolatedAPIRequestContext instance.
        """
        cookies: list[dict] = []
        if storage_state is not None:
            if isinstance(storage_state, (str, pathlib.Path)):
                file_path = pathlib.Path(storage_state)
                if not file_path.exists():
                    raise FileNotFoundError(f"Storage state file not found: {file_path}")
                try:
                    with open(file_path) as f:
                        state = json.load(f)
                except json.JSONDecodeError as e:
                    raise ValueError(f"Invalid JSON in storage state file {file_path}: {e}") from e
                except OSError as e:
                    raise OSError(f"Cannot read storage state file {file_path}: {e}") from e
            else:
                state = storage_state
            cookies = list(state.get("cookies", []))

        return _IsolatedAPIRequestContext(
            base_url=base_url,
            extra_headers=extra_headers,
            cookies=cookies,
            timeout=self._timeout,
            max_redirects=self._max_redirects,
            fail_on_status_code=fail_on_status_code,

View on GitHub (pinned to aa36b38e69)

Solutions

1. Verify the path exists: `if not pathlib.Path(p).exists(): raise ...` before calling.
2. Generate the file first via `storage_state(path=...)` from a logged-in session.
3. Pass a dict directly to skip the file: `new_context(storage_state={"cookies": [...]})`.
4. Use an absolute path anchored to the script location.

Example fix

// before
ctx = api.new_context(storage_state="state.json")  # FileNotFoundError
// after
import pathlib
p = pathlib.Path(__file__).parent / "state.json"
ctx = api.new_context(storage_state=str(p))  # after generating it

import pathlib
p = pathlib.Path("state.json")
assert p.exists(), f"storage state file missing: {p}"
ctx = api.new_context(storage_state=str(p))

import pathlib
def storage_state_file_exists(value) -> bool:
    return pathlib.Path(value).exists()

try:
    ctx = api.new_context(storage_state=path)
except FileNotFoundError:
    ctx = api.new_context(storage_state={"cookies": []})  # fallback to empty state

When it happens

Trigger: `new_context(storage_state="/nope/state.json")`, `new_context(storage_state=Path("state.json"))` where the file was never created, or a relative path that does not resolve from the CWD.

Common situations: CI runs where the storage-state artifact was not generated/downloaded. Path typos. Relative paths breaking across machines. Generating the file in a previous step that failed.

Related errors

• Cannot read storage state file {file_path}: {e}
• Cannot write storage state to {file_path}: {e}
• Invalid JSON in storage state file {file_path}: {e}
• Params must be an instance of CookieFilter. Received:'${cook
• Path to the extension doesn't exist

AI-assisted analysis of SeleniumHQ/selenium@aa36b38e69 (2026-08-14). Data as JSON: /api/errors/f0f515fdbd5c74f6. Report an issue: GitHub.