xtekky/gpt4free · error · ImportError

Install "websocket-client" package: pip install websocket-cl

Error message

Install "websocket-client" package: pip install websocket-client

What it means

Raised by SyncCDPSession._connect() in g4f/requests/cdp.py when `from websocket import create_connection` fails — the synchronous CDP client deliberately uses the websocket-client package (not aiohttp), and it is an optional dependency. The ImportError surfaces with the exact pip command needed.

Source

Thrown at g4f/requests/cdp.py:752

                    target = json.loads(response.read().decode("utf-8"))
                    ws_url = target.get("webSocketDebuggerUrl")
                    self.target_id = target.get("id")
                    if ws_url:
                        break
            except Exception:
                time.sleep(0.5)

        if not ws_url:
            raise RuntimeError(f"Failed to create new tab target on port {self.port}")

        self._connect(ws_url)

    def _connect(self, ws_url: str):
        """Connect via WebSocket to the target."""
        try:
            from websocket import create_connection
        except ImportError:
            raise ImportError(
                'Install "websocket-client" package: pip install websocket-client'
            )

        self.ws = create_connection(ws_url)
        self.ws.settimeout(60)  # Prevent infinite hang if Chrome crashes mid-call

        # Enable essential CDP domains
        self.call("Page.enable")
        self.call("DOM.enable")
        self.call("Runtime.enable")
        self.call("Network.enable")
        self.call("Emulation.setFocusEmulationEnabled", enabled=True)

    def call(self, method: str, **params) -> dict:
        """Send a CDP command and block until the matching response arrives, logging events."""
        self.id_counter += 1
        payload = {"id": self.id_counter, "method": method, "params": params}
        self.ws.send(json.dumps(payload))

View on GitHub (pinned to 973504e177)

Solutions

pip install websocket-client (exact command in the message), then retry.
Verify: python -c "from websocket import create_connection".
Alternatively use the async CDPSession which depends on aiohttp instead.

Defensive patterns

Strategy: validation

Validate before calling

def has_sync_cdp() -> bool:
    try:
        from websocket import create_connection  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    session = SyncCDPSession(port=9222); session.start_chrome()
except ImportError as e:
    raise SystemExit(str(e))  # prints the exact pip install command

Prevention

Include websocket-client in requirements when using SyncCDPSession.
Detect it at startup rather than mid-request.
Remember async CDPSession uses aiohttp instead — pick deps to match the client used.

When it happens

Trigger: Using SyncCDPSession (or a provider that internally uses it, e.g. Turnstile solvers) in an environment where websocket-client is not installed. The tab target was already created successfully, so the browser side is fine — only the Python client library is missing.

Common situations: Installing only the async CDP deps (aiohttp) but using the sync client; minimal dependency installs; websocket-client uninstalled as 'unused' by a dependency cleaner.

Related errors

AI-assisted analysis of xtekky/gpt4free@973504e177 (2026-08-14). Data as JSON: /api/errors/7e4613d5f60f2276. Report an issue: GitHub.