SeleniumHQ/selenium · error · TypeError

Debugger Address must be a string

Error message

Debugger Address must be a string

What it means

The `debugger_address` setter on `ChromiumOptions` requires a `str` of the form `hostname[:port]`, used to connect to a running DevTools instance for an 'active wait' connection. Non-string values are rejected. This lets you attach Selenium to an already-running Chrome started with `--remote-debugging-port`.

Source

Thrown at py/selenium/webdriver/chromium/options.py:68

        """
        if not isinstance(value, str):
            raise TypeError(self.BINARY_LOCATION_ERROR)
        self._binary_location = value

    @property
    def debugger_address(self) -> str | None:
        """Returns the address of the remote devtools instance."""
        return self._debugger_address

    @debugger_address.setter
    def debugger_address(self, value: str) -> None:
        """Set the address of the remote devtools instance for active wait connection.

        Args:
            value: Address of remote devtools instance if any (hostname[:port]).
        """
        if not isinstance(value, str):
            raise TypeError("Debugger Address must be a string")
        self._debugger_address = value

    @property
    def extensions(self) -> list[str]:
        """Returns a list of encoded extensions that will be loaded."""

        def _decode(file_data: BinaryIO) -> str:
            # Should not use base64.encodestring() which inserts newlines every
            # 76 characters (per RFC 1521).  Chromedriver has to remove those
            # unnecessary newlines before decoding, causing performance hit.
            return base64.b64encode(file_data.read()).decode("utf-8")

        encoded_extensions = []
        for extension in self._extension_files:
            with open(extension, "rb") as f:
                encoded_extensions.append(_decode(f))

        return encoded_extensions + self._extensions

View on GitHub (pinned to aa36b38e69)

Solutions

1. Pass the full host:port string: `options.debugger_address = "localhost:9222"`.
2. Build it from components: `options.debugger_address = f"{host}:{port}"`.
3. Leave it unset if you are not attaching to an existing DevTools endpoint.

Example fix

// before
options.debugger_address = 9222  # TypeError
// after
options.debugger_address = "localhost:9222"

host, port = "localhost", 9222
addr = host if ":" in host else f"{host}:{port}"
assert isinstance(addr, str) and addr, "debugger_address must be a non-empty host[:port] string"
options.debugger_address = addr

def is_debugger_address(value) -> bool:
    return isinstance(value, str) and len(value) > 0

try:
    options.debugger_address = addr
except TypeError:
    options.debugger_address = f"localhost:{addr}" if isinstance(addr, int) else str(addr)

When it happens

Trigger: `options.debugger_address = 9222` (passing an int port alone), `options.debugger_address = ("localhost", 9222)` (a tuple), or `options.debugger_address = None`. The address must include the hostname.

Common situations: Confusing the address with just a port number. Passing a tuple from a config object. Forgetting to disable it when reusing options across sessions.

Related errors

• Binary Location Must be a String
• ClipRectangle must be an instance of ClipRectangle. Received
• Value must be an instance of BytesValue. Received: '${value}
• CookieHeader must be an instance of Header. Received:'${head
• Header value must be an instance of Header. Received:'${head

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