{"record":{"id":"8764b318a5b4a599","repo":"SeleniumHQ/selenium","slug":"binary-location-must-be-a-string-8764b3","errorCode":null,"errorMessage":"Binary Location Must be a String","messagePattern":"Binary Location Must be a String","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"py/selenium/webdriver/firefox/options.py","lineNumber":57,"sourceCode":"        super().__init__()\n        self._binary_location = \"\"\n        self._preferences: dict = {}\n        # https://fxdx.dev/deprecating-cdp-support-in-firefox-embracing-the-future-with-webdriver-bidi/.\n        # Enable BiDi only\n        self._preferences[\"remote.active-protocols\"] = 1\n        self._profile: FirefoxProfile | None = None\n        self.log = Log()\n\n    @property\n    def binary_location(self) -> str:\n        \"\"\"Returns the location of the binary.\"\"\"\n        return self._binary_location\n\n    @binary_location.setter\n    def binary_location(self, value: str) -> None:\n        \"\"\"Sets the location of the browser binary by string.\"\"\"\n        if not isinstance(value, str):\n            raise TypeError(self.BINARY_LOCATION_ERROR)\n        self._binary_location = value\n\n    @property\n    def preferences(self) -> dict:\n        \"\"\"Returns a dict of preferences.\"\"\"\n        return self._preferences\n\n    def set_preference(self, name: str, value: str | int | bool):\n        \"\"\"Sets a preference.\"\"\"\n        self._preferences[name] = value\n\n    @property\n    def profile(self) -> FirefoxProfile | None:\n        \"\"\"Returns the Firefox profile to use.\"\"\"\n        return self._profile\n\n    @profile.setter\n    def profile(self, new_profile: str | FirefoxProfile) -> None:","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/SeleniumHQ/selenium/blob/aa36b38e696a0909e973bdf5e2f9031ffe842c4b/py/selenium/webdriver/firefox/options.py#L39-L75","documentation":"Raised as TypeError by the FirefoxOptions.binary_location setter when the value is not a Python str. The setter strictly checks isinstance(value, str) because the binary location is passed to Firefox as a filesystem path, and non-string types would cause failures later in the driver launch process.","triggerScenarios":"Assigning options.binary_location = Path('/usr/bin/firefox') (a pathlib.Path), or options.binary_location = None, or options.binary_location = b'/usr/bin/firefox' (bytes) triggers the TypeError.","commonSituations":"Developers using pathlib.Path objects (common in modern Python) without converting to string. Configuration from JSON that deserializes as non-string types. Passing None when no binary override is intended.","solutions":["Convert pathlib.Path to string: options.binary_location = str(path)","If no override is needed, do not set binary_location at all (leave the default empty string)","Ensure the value is a plain Python str before assignment"],"exampleFix":"// before\nfrom pathlib import Path\noptions.binary_location = Path('/usr/bin/firefox')\n\n// after\nfrom pathlib import Path\noptions.binary_location = str(Path('/usr/bin/firefox'))","handlingStrategy":"type-guard","validationCode":"from pathlib import Path\nbinary = Path('/usr/bin/firefox')\noptions.binary_location = str(binary) if isinstance(binary, Path) else binary","typeGuard":"def is_str(v) -> bool:\n    return isinstance(v, str)","tryCatchPattern":"try:\n    options.binary_location = value\nexcept TypeError:\n    options.binary_location = str(value)","preventionTips":["Always convert pathlib.Path to str before assignment","Do not set binary_location if no override is needed","Ensure the value is a plain str, not bytes or None"],"tags":["firefox","type-validation","options","binary","string"],"backgroundTag":null,"analyzedSha":"aa36b38e696a0909e973bdf5e2f9031ffe842c4b","analyzedAt":"2026-08-14T02:32:32.244Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}