From brightdata-pack
Diagnoses and fixes Bright Data errors like 407 Proxy Authentication, 502 Bad Gateway, SSL certificate failures, connection timeouts, inactive zones, and 429 rate limits using curl tests and config tweaks.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin brightdata-packThis skill is limited to using the following tools:
Diagnostic reference for the most common Bright Data proxy and API errors with real solutions and fix commands.
Collects Bright Data proxy debug bundle: environment info, credential checks, SSL certs, curl connectivity tests with headers. For support tickets.
Debugs Bright Data Scraping Browser sessions via Browser Sessions API for errors, puppeteer traces, bandwidth, captchas, connection issues, and unexpected results like empty data.
Automates Brightdata operations like web scraping and proxy management via Composio toolkit and Rube MCP. Discovers tools dynamically with RUBE_SEARCH_TOOLS, manages connections, and executes workflows.
Share bugs, ideas, or general feedback.
Diagnostic reference for the most common Bright Data proxy and API errors with real solutions and fix commands.
Check your proxy response status code or error message against the table below.
Follow the specific solution for your error code.
HTTP/1.1 407 Proxy Authentication Required
Cause: Username format is wrong or credentials are invalid.
Fix:
# Verify credential format — must be exactly:
# brd-customer-{CUSTOMER_ID}-zone-{ZONE_NAME}
echo "Username: brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}"
# Test with curl
curl -x "http://brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}:${BRIGHTDATA_ZONE_PASSWORD}@brd.superproxy.io:33335" \
https://lumtest.com/myip.json
HTTP/1.1 502 Bad Gateway
X-Luminati-Error: target_site_blocked
Cause: Target site blocked the request despite Web Unlocker retries.
Fix:
-country-us to username for geo-specific contentError: SSL: CERTIFICATE_VERIFY_FAILED
Cause: Missing Bright Data CA certificate for HTTPS proxying.
Fix:
# Download the Bright Data CA certificate
curl -sO https://brightdata.com/ssl/brd-ca.crt
# Node.js
export NODE_EXTRA_CA_CERTS=./brd-ca.crt
# Python requests
# requests.get(url, proxies=proxies, verify='./brd-ca.crt')
Error: connect ETIMEDOUT brd.superproxy.io:33335
Cause: Firewall blocking outbound connections to Bright Data.
Fix:
# Test connectivity
nc -zv brd.superproxy.io 33335
# If blocked, allow outbound TCP to brd.superproxy.io:33335
# For Scraping Browser, also allow port 9222
nc -zv brd.superproxy.io 9222
Cause: Zone is not active or has been paused.
Fix: Go to https://brightdata.com/cp, navigate to the zone, and click "Activate".
Cause: Exceeded concurrent request limit for your zone.
Fix:
// Implement request queuing
import PQueue from 'p-queue';
const queue = new PQueue({ concurrency: 10, interval: 1000, intervalCap: 20 });
const result = await queue.add(() => client.get(url));
Cause: Target returned a CAPTCHA page that Web Unlocker couldn't solve, or wrong zone type for the target.
Fix:
&brd_json=1 for SERP API requestsBright Data returns error details in response headers:
| Header Value | Meaning | Action |
|---|---|---|
target_site_blocked | Site anti-bot blocked request | Use Scraping Browser |
ip_banned | IP was banned by target | Retry (auto-rotates IP) |
captcha | CAPTCHA challenge failed | Increase timeout |
connection_failed | Could not reach target | Verify target URL |
auth_failed | Credential error | Check username/password |
# Check Bright Data status
curl -s https://status.brightdata.com/api/v2/status.json | python3 -m json.tool
# Test proxy connectivity
curl -x "http://brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}:${BRIGHTDATA_ZONE_PASSWORD}@brd.superproxy.io:33335" \
-o /dev/null -s -w "HTTP %{http_code} in %{time_total}s\n" \
https://lumtest.com/myip.json
# Check zone credentials
curl -H "Authorization: Bearer ${BRIGHTDATA_API_TOKEN}" \
https://api.brightdata.com/zone/get_active_zones
X-Luminati-* headers)brightdata-debug-bundle to create diagnostic packageFor comprehensive debugging, see brightdata-debug-bundle.