ScreenshotEncodingError
browser_use.errors.ScreenshotEncodingError
Stack trace
browser_use.errors.ScreenshotEncodingError: Failed to encode screenshot image: unsupported format or corrupted data
File "/app/browser_use/capture.py", line 87, in capture_screenshot
encoded_image = encode_image(raw_image, format='png')
File "/app/browser_use/encoding.py", line 45, in encode_image
raise ScreenshotEncodingError("Failed to encode screenshot image: unsupported format or corrupted data") Why it happens
This error occurs when the raw screenshot data captured from the browser cannot be properly encoded into the target image format (e.g., PNG or JPEG). Causes include corrupted raw image data, unsupported image formats, or missing image encoding libraries.
Detection
Monitor screenshot capture logs for ScreenshotEncodingError exceptions and validate that raw image buffers are non-empty and in a supported format before encoding.
Causes & fixes
Raw screenshot data is corrupted or incomplete due to browser capture failure
Add validation to check raw image data integrity before encoding and retry capture if data is invalid.
Unsupported image format requested for encoding (e.g., 'bmp' not supported)
Use a supported image format like 'png' or 'jpeg' explicitly when calling the encoding function.
Required image encoding libraries (e.g., Pillow) are missing or outdated
Install or upgrade the Pillow library with 'pip install --upgrade Pillow' to ensure encoding support.
Code: broken vs fixed
from browser_use import capture_screenshot
image_data = capture_screenshot(format='bmp') # triggers ScreenshotEncodingError
print('Screenshot captured')import os
from browser_use import capture_screenshot
os.environ['BROWSER_USE_API_KEY'] = os.getenv('BROWSER_USE_API_KEY') # Use env var for API key
image_data = capture_screenshot(format='png') # fixed format to supported 'png'
print('Screenshot captured successfully')Workaround
Catch ScreenshotEncodingError exceptions, log the raw image data size and type, then retry the screenshot capture with a fallback format like 'png'.
Prevention
Always validate raw screenshot data before encoding and use supported image formats with up-to-date encoding libraries to avoid encoding failures.