| name | brightdata-common-errors |
| description | Diagnose and fix Bright Data common errors and exceptions.
Use when encountering Bright Data errors, debugging failed requests,
or troubleshooting integration issues.
Trigger with phrases like "brightdata error", "fix brightdata",
"brightdata not working", "debug brightdata".
|
| allowed-tools | Read, Grep, Bash(curl:*) |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","scraping","data","brightdata"] |
| compatibility | Designed for Claude Code |
Bright Data Common Errors
Overview
Diagnostic reference for the most common Bright Data proxy and API errors with real solutions and fix commands.
Prerequisites
- Bright Data zone configured
- Proxy credentials available
- Access to error logs
Instructions
Step 1: Identify the Error
Check your proxy response status code or error message against the table below.
Step 2: Apply the Fix
Follow the specific solution for your error code.
Error Reference
407 Proxy Authentication Required
HTTP/1.1 407 Proxy Authentication Required
Cause: Username format is wrong or credentials are invalid.
Fix:
echo "Username: brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}"
curl -x "http://brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}:${BRIGHTDATA_ZONE_PASSWORD}@brd.superproxy.io:33335" \
https://lumtest.com/myip.json
502 Bad Gateway
HTTP/1.1 502 Bad Gateway
X-Luminati-Error: target_site_blocked
Cause: Target site blocked the request despite Web Unlocker retries.
Fix:
- Increase timeout to 120s (Web Unlocker needs time to solve CAPTCHAs)
- Switch to Scraping Browser zone for JS-heavy sites
- Add
-country-us to username for geo-specific content
SSL Certificate Errors
Error: SSL: CERTIFICATE_VERIFY_FAILED
Cause: Missing Bright Data CA certificate for HTTPS proxying.
Fix:
curl -sO https://brightdata.com/ssl/brd-ca.crt
export NODE_EXTRA_CA_CERTS=./brd-ca.crt
