{"record":{"id":"9054cd6b9ec4929a","repo":"D4Vinci/Scrapling","slug":"quality-is-only-valid-when-image-type-is-jpeg","errorCode":null,"errorMessage":"'quality' is only valid when 'image_type' is 'jpeg'.","messagePattern":"'quality' is only valid when 'image_type' is 'jpeg'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"scrapling/core/ai.py","lineNumber":345,"sourceCode":"        network_idle: bool = False,\n        timeout: int | float = 30000,\n    ) -> List[ImageContent | TextContent]:\n        \"\"\"Capture a screenshot of a web page using an existing browser session and return it as an image.\n        A browser session must be opened first with `open_session` (either `dynamic` or `stealthy`); the session ID is then passed here.\n\n        :param url: The URL to navigate to and capture.\n        :param session_id: ID of an open browser session created with `open_session`.\n        :param image_type: Image format. Defaults to \"png\". Use \"jpeg\" for smaller file sizes.\n        :param full_page: When True, captures the full scrollable page instead of just the viewport. Defaults to False.\n        :param quality: Image quality (0-100) for JPEG only. Raises if passed with `image_type=\"png\"`.\n        :param wait: Time in milliseconds to wait after page load before capturing. Defaults to 0.\n        :param wait_selector: Optional CSS selector to wait for before capturing.\n        :param wait_selector_state: State to wait for the selector. Defaults to \"attached\".\n        :param network_idle: Wait for the page until there are no network connections for at least 500 ms.\n        :param timeout: Timeout in milliseconds for page operations. Defaults to 30,000.\n        \"\"\"\n        if quality is not None and image_type != \"jpeg\":\n            raise ValueError(\"'quality' is only valid when 'image_type' is 'jpeg'.\")\n\n        entry = self._get_session(session_id, expected_type=None)\n\n        screenshot_kwargs: Dict[str, Any] = {\"type\": image_type, \"full_page\": full_page}\n        if quality is not None:\n            screenshot_kwargs[\"quality\"] = quality\n\n        captured: Dict[str, Any] = {}\n\n        async def _capture(page: Any) -> None:\n            try:\n                captured[\"bytes\"] = await page.screenshot(**screenshot_kwargs)\n                captured[\"url\"] = page.url\n            except Exception as exc:\n                captured[\"error\"] = exc\n\n        await entry.session.fetch(\n            url,","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/D4Vinci/Scrapling/blob/5d213a2d4764002bfc4fed33c32fe09fa8b0bf7f/scrapling/core/ai.py#L327-L363","documentation":"capture_screenshot accepts a quality parameter (JPEG quality 0-100) but Playwright only supports quality for JPEG output. If quality is passed while image_type is 'png' (the default), the server rejects the combination before touching the browser. This mirrors Playwright's own constraint, raised early for a clear message.","triggerScenarios":"Calling screenshot with image_type='png' (explicitly or by default) together with quality=80, or setting quality globally in agent config while switching image_type to png for lossless captures.","commonSituations":"Copy-pasting a full option set from a JPEG example, or LLM agents filling every optional argument with defaults.","solutions":["Use quality only with image_type='jpeg': screenshot(url, image_type='jpeg', quality=80)","Or drop quality entirely for png output"],"exampleFix":"# before\nawait capture_screenshot(session_id=sid, url=url, image_type='png', quality=80)\n\n# after\nawait capture_screenshot(session_id=sid, url=url, image_type='jpeg', quality=80)","handlingStrategy":"validation","validationCode":"if quality is not None:\n    assert image_type == 'jpeg', 'quality requires image_type=\"jpeg\"'","typeGuard":"from typing import Optional\n\ndef screenshot_args_ok(image_type: str, quality: Optional[int]) -> bool:\n    return quality is None or image_type == 'jpeg'","tryCatchPattern":null,"preventionTips":["Only forward quality when the caller explicitly chose jpeg","Define tool schemas so quality is only exposed alongside image_type='jpeg'"],"tags":["ai","mcp","screenshot","validation","playwright"],"backgroundTag":null,"analyzedSha":"5d213a2d4764002bfc4fed33c32fe09fa8b0bf7f","analyzedAt":"2026-08-14T22:23:09.440Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}