{"record":{"id":"792951f6f12a5647","repo":"crewAIInc/crewAI","slug":"stagehand-package-not-found-please-run-uv-add","errorCode":null,"errorMessage":"`stagehand` package not found, please run `uv add stagehand`","messagePattern":"`stagehand` package not found, please run `uv add stagehand`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/tools/stagehand_tool/stagehand_tool.py","lineNumber":241,"sourceCode":"        if wait_for_captcha_solves is not None:\n            self.wait_for_captcha_solves = wait_for_captcha_solves\n        if verbose is not None:\n            self.verbose = verbose\n\n        self._session_id = session_id\n\n        if not self._testing:\n            log_level = {1: \"INFO\", 2: \"WARNING\", 3: \"DEBUG\"}.get(self.verbose, \"ERROR\")\n            configure_logging(\n                level=log_level, remove_logger_name=True, quiet_dependencies=True\n            )\n\n        self._check_required_credentials()\n\n    def _check_required_credentials(self) -> None:\n        \"\"\"Validate that required credentials are present.\"\"\"\n        if not self._testing and not _HAS_STAGEHAND:\n            raise ImportError(\n                \"`stagehand` package not found, please run `uv add stagehand`\"\n            )\n\n        if not self.api_key:\n            raise ValueError(\"api_key is required (or set BROWSERBASE_API_KEY in env).\")\n        if not self.project_id:\n            raise ValueError(\n                \"project_id is required (or set BROWSERBASE_PROJECT_ID in env).\"\n            )\n\n    def __del__(self) -> None:\n        \"\"\"Ensure cleanup on deletion.\"\"\"\n        try:\n            self.close()\n        except Exception:  # noqa: S110\n            pass\n\n    def _get_model_api_key(self) -> str | None:","sourceCodeStart":223,"sourceCodeEnd":259,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/stagehand_tool/stagehand_tool.py#L223-L259","documentation":"StagehandTool checks at construction time (_check_required_credentials) that the stagehand Python package is importable; if not (and the tool is not in _testing mode) it raises ImportError with the install command `uv add stagehand`. The check uses a module-level _HAS_STAGEHAND flag rather than a prompt — this tool does not offer auto-install.","triggerScenarios":"Instantiating StagehandTool without the stagehand package installed; environments where pip install crewai-tools did not pull stagehand (it is an optional dependency). Testing mode (_testing=True) deliberately bypasses it.","commonSituations":"Optional-dependency setups where stagehand wasn't installed; fresh clones running tests/dev environments; Docker images built without the stagehand extra.","solutions":["Install the package: uv add stagehand (or pip install stagehand).","Add stagehand to your project dependencies/Dockerfile.","If writing unit tests of your own orchestration (not the tool), construct the tool with _testing=True to skip dependency and credential checks."],"exampleFix":"# terminal\n# before: StagehandTool() -> ImportError\n\n# after:\n#   pip install stagehand\nfrom crewai_tools import StagehandTool\ntool = StagehandTool()","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec(\"stagehand\") is None:\n    raise RuntimeError(\"Run: pip install stagehand\")","typeGuard":null,"tryCatchPattern":"try:\n    tool = StagehandTool()\nexcept ImportError as e:\n    if \"stagehand\" in str(e):\n        subprocess.run([\"pip\", \"install\", \"stagehand\"], check=True)\n        tool = StagehandTool()","preventionTips":["Add stagehand to your dependency manifest; it is optional and never auto-installed by this tool.","Use _testing=True only for unit tests of surrounding orchestration, never to bypass the check in production."],"tags":["stagehand","dependency","installation","browserbase"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}