SeleniumHQ/selenium · error · OSError

Cannot read storage state file {file_path}: {e}

Error message

Cannot read storage state file {file_path}: {e}

What it means

While reading the storage-state file, if an `OSError` occurs that is not a JSON decode error (e.g. permission denied, broken symlink, disk read error), Selenium re-raises it as `OSError` with the path and the underlying error. This distinguishes OS-level read problems from JSON syntax problems.

Source

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

            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,
        )

    def get_storage_state(self, path: str | pathlib.Path | None = None) -> dict[str, Any]:
        """Export the current browser cookies as a storage state dict.

        Args:
            path: Optional file path to save the storage state as JSON.

View on GitHub (pinned to aa36b38e69)

Solutions

1. Check permissions: `os.access(p, os.R_OK)` and chmod/chown as needed.
2. Ensure the file is a regular file: `pathlib.Path(p).is_file()`.
3. Run the process as a user with read access to the file.
4. Move the file to a location the process owns.

Example fix

// before
ctx = api.new_context(storage_state="/root/state.json")  # OSError: permission
// after
# copy to a readable location first
import shutil; shutil.copy("/root/state.json", "./state.json")
ctx = api.new_context(storage_state="./state.json")

import os
p = "state.json"
assert os.access(p, os.R_OK), f"storage state file not readable: {p}"
ctx = api.new_context(storage_state=p)

import os
def storage_state_file_readable(path) -> bool:
    return os.access(path, os.R_OK)

try:
    ctx = api.new_context(storage_state=path)
except OSError as e:
    # permission/IO issue; copy to a readable location or pass a dict
    ctx = api.new_context(storage_state=json.load(open(local_copy)))

When it happens

Trigger: File exists and is valid JSON but is unreadable due to permissions (`PermissionError`), a broken symlink, a lock, or a transient I/O error. The file is a directory (though `is_file` would normally catch that earlier).

Common situations: File owned by another user / wrong mode in shared CI. NFS/network filesystem read hiccups. Antivirus locking the file. Container volume permission mismatch.

Related errors

• Storage state file not found: {file_path}
• Cannot write storage state to {file_path}: {e}
• Invalid JSON in storage state file {file_path}: {e}
• not executable: #{path.inspect}
• Invalid permission state. Must be one of: ${Object.values(Pe

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