{"record":{"id":"c00d32a583ff9e6b","repo":"browser-use/browser-use","slug":"llm-screenshot-size-must-be-a-tuple-of-width-hei","errorCode":null,"errorMessage":"llm_screenshot_size must be a tuple of (width, height)","messagePattern":"llm_screenshot_size must be a tuple of \\(width, height\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"browser_use/agent/service.py","lineNumber":217,"sourceCode":"\t\tinclude_recent_events: bool = False,\n\t\tsample_images: list[ContentPartTextParam | ContentPartImageParam] | None = None,\n\t\tfinal_response_after_failure: bool = True,\n\t\tenable_planning: bool = True,\n\t\tplanning_replan_on_stall: int = 3,\n\t\tplanning_exploration_limit: int = 5,\n\t\tloop_detection_window: int = 20,\n\t\tloop_detection_enabled: bool = True,\n\t\tllm_screenshot_size: tuple[int, int] | None = None,\n\t\tmessage_compaction: MessageCompactionSettings | bool | None = True,\n\t\tmax_clickable_elements_length: int = 40000,\n\t\t_url_shortening_limit: int = 25,\n\t\tenable_signal_handler: bool = True,\n\t\t**kwargs,\n\t):\n\t\t# Validate llm_screenshot_size\n\t\tif llm_screenshot_size is not None:\n\t\t\tif not isinstance(llm_screenshot_size, tuple) or len(llm_screenshot_size) != 2:\n\t\t\t\traise ValueError('llm_screenshot_size must be a tuple of (width, height)')\n\t\t\twidth, height = llm_screenshot_size\n\t\t\tif not isinstance(width, int) or not isinstance(height, int):\n\t\t\t\traise ValueError('llm_screenshot_size dimensions must be integers')\n\t\t\tif width < 100 or height < 100:\n\t\t\t\traise ValueError('llm_screenshot_size dimensions must be at least 100 pixels')\n\t\t\tself.logger.info(f'🖼️  LLM screenshot resizing enabled: {width}x{height}')\n\t\tif llm is None:\n\t\t\tdefault_llm_name = CONFIG.DEFAULT_LLM\n\t\t\tif default_llm_name:\n\t\t\t\tfrom browser_use.llm.models import get_llm_by_name\n\n\t\t\t\tllm = get_llm_by_name(default_llm_name)\n\t\t\telse:\n\t\t\t\t# No default LLM specified, use the original default\n\t\t\t\tfrom browser_use import ChatBrowserUse\n\n\t\t\t\tllm = ChatBrowserUse()\n","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/browser-use/browser-use/blob/6c73fced2f6d45a11d88622fe56365a5fe18f28b/browser_use/agent/service.py#L199-L235","documentation":"Agent.__init__ validation: llm_screenshot_size was provided but is not a 2-tuple. The parameter resizes screenshots sent to the LLM; the constructor requires exactly tuple(width, height) before it even looks at the LLM, failing fast on malformed config.","triggerScenarios":"Passing a list [1280, 720] instead of a tuple; passing a single int; passing a 3-element tuple; passing None inside a config dict that gets unpacked with a wrong shape; passing a string '1280x720'.","commonSituations":"Loading Agent options from JSON/YAML where sequences arrive as lists; copy-pasting viewport-style dicts ({'width':..,'height':..}) which the Browser accepts but Agent does not for this param.","solutions":["Convert to a tuple: llm_screenshot_size=(1280, 720)","When loading from config: llm_screenshot_size=tuple(cfg['llm_screenshot_size'])","Note the neighboring parameter (Browser window_size) accepts dicts — do not mix the two conventions"],"exampleFix":"# before\nagent = Agent(task=..., llm=llm, llm_screenshot_size=[1024, 768])\n\n# after\nagent = Agent(task=..., llm=llm, llm_screenshot_size=(1024, 768))","handlingStrategy":"type-guard","validationCode":"def normalize_screenshot_size(v):\n    if v is None:\n        return None\n    v = tuple(v)\n    assert len(v) == 2, 'llm_screenshot_size must have 2 items'\n    return v\n\nagent = Agent(task=..., llm=llm, llm_screenshot_size=normalize_screenshot_size(cfg_size))","typeGuard":"def is_valid_screenshot_size(v) -> bool:\n    return v is None or (isinstance(v, tuple) and len(v) == 2)","tryCatchPattern":"null","preventionTips":["Always write the literal as a tuple (w, h)","Normalize config-file sequences to tuples at load time"],"tags":["configuration","validation","screenshot"],"backgroundTag":null,"analyzedSha":"6c73fced2f6d45a11d88622fe56365a5fe18f28b","analyzedAt":"2026-08-14T19:42:40.557Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}