{"record":{"id":"abbe0828ab6614d1","repo":"unclecode/crawl4ai","slug":"cannot-create-new-browser-contexts-when-using-use","errorCode":null,"errorMessage":"Cannot create new browser contexts when using use_persistent_context=True. Persistent context uses a single shared context.","messagePattern":"Cannot create new browser contexts when using use_persistent_context=True\\. Persistent context uses a single shared context\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"crawl4ai/browser_manager.py","lineNumber":1263,"sourceCode":"            \"\"\")\n            context._crawl4ai_shadow_dom_injected = True\n\n        # Apply custom init_scripts from BrowserConfig (for stealth evasions, etc.)\n        if self.config.init_scripts:\n            for script in self.config.init_scripts:\n                await context.add_init_script(script)\n\n    async def create_browser_context(self, crawlerRunConfig: CrawlerRunConfig = None):\n        \"\"\"\n        Creates and returns a new browser context with configured settings.\n        Applies text-only mode settings if text_mode is enabled in config.\n\n        Returns:\n            Context: Browser context object with the specified configurations\n        \"\"\"\n        if self.browser is None:\n            if self._launched_persistent:\n                raise RuntimeError(\n                    \"Cannot create new browser contexts when using \"\n                    \"use_persistent_context=True. Persistent context uses a \"\n                    \"single shared context.\"\n                )\n            raise RuntimeError(\n                \"Browser is not available. It may have been closed, crashed, \"\n                \"or not yet started. Ensure the browser is running before \"\n                \"creating new contexts.\"\n            )\n        # Base settings\n        user_agent = self.config.headers.get(\"User-Agent\", self.config.user_agent) \n        viewport_settings = {\n            \"width\": self.config.viewport_width,\n            \"height\": self.config.viewport_height,\n        }\n        proxy_settings = {\"server\": self.config.proxy} if self.config.proxy else None\n\n        # CSS extensions (blocked separately via avoid_css flag)","sourceCodeStart":1245,"sourceCodeEnd":1281,"githubUrl":"https://github.com/unclecode/crawl4ai/blob/7e801521428ee12509994d39151006f64055ebe3/crawl4ai/browser_manager.py#L1245-L1281","documentation":"create_browser_context() refuses to make new contexts when self.browser is None AND the manager was launched with use_persistent_context=True (flag _launched_persistent). A persistent-context Playwright launch returns a single shared context instead of a Browser object, so new-context creation is structurally impossible.","triggerScenarios":"BrowserConfig(use_persistent_context=True) combined with session-per-crawl behavior that calls create_browser_context() for each new session (e.g. multiple concurrent crawlers sharing one manager, or explicitly requesting a new context).","commonSituations":"Enabling persistent contexts for logged-in sessions then attempting parallel crawls that each want isolated contexts; library code (deep crawling, dispatcher) that assumes context creation is always available.","solutions":["Reuse the existing persistent context instead of creating new ones: access crawler.crawler_strategy.browser_context or the shared context rather than calling create_browser_context().","If you need isolated contexts, disable persistence: BrowserConfig(use_persistent_context=False) and store auth state with storage_state instead.","Run one crawler at a time per persistent profile."],"exampleFix":"# before\nBrowserConfig(use_persistent_context=True)\n# ... later: ctx = await manager.create_browser_context()  # RuntimeError\n\n# after\nBrowserConfig(use_persistent_context=False, storage_state='auth.json')\nctx = await manager.create_browser_context()  # works","handlingStrategy":"validation","validationCode":"if browser_config.use_persistent_context and need_isolated_contexts:\n    raise ValueError('use_persistent_context cannot be combined with per-session contexts; use storage_state instead')","typeGuard":"def can_create_contexts(browser_config) -> bool:\n    return not getattr(browser_config, 'use_persistent_context', False)","tryCatchPattern":"try:\n    ctx = await manager.create_browser_context(cfg)\nexcept RuntimeError as e:\n    if 'use_persistent_context=True' in str(e):\n        ctx = manager.browser_context  # reuse the shared persistent context\n    else:\n        raise","preventionTips":["Decide upfront: persistent shared context OR isolated contexts with storage_state.","Don't run parallel context-per-session designs with use_persistent_context=True.","Document that persistent mode exposes exactly one context."],"tags":["browser-manager","persistent-context","configuration"],"backgroundTag":null,"analyzedSha":"7e801521428ee12509994d39151006f64055ebe3","analyzedAt":"2026-08-14T20:46:20.673Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}