brightdata-common-errors
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".
- License 许可
- MIT
- 最近更新
- 2026-07-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- brightdata-common-errors
- tags
- [ "saas", "scraping", "data", "brightdata" ]
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- license
- MIT
- version
- 1.0.0
- 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:*)
- compatible-with
- claude-code
03 SKILL.md 正文
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:
# 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
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-usto username for geo-specific content
SSL Certificate Errors
Error: 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')
ETIMEDOUT / Connection Timeout
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
403 Forbidden (Zone Inactive)
Cause: Zone is not active or has been paused.
Fix: Go to https://brightdata.com/cp, navigate to the zone, and click "Activate".
429 Too Many Requests
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));
Empty Response Body
Cause: Target returned a CAPTCHA page that Web Unlocker couldn't solve, or wrong zone type for the target.
Fix:
- Check zone type matches target (Web Unlocker for static, Scraping Browser for JS)
- Verify target URL is accessible in a regular browser
- Try adding
&brd_json=1for SERP API requests
X-Luminati-Error Headers
Bright 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 |
Quick Diagnostic Commands
# 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
Escalation Path
- Collect request/response headers (including
X-Luminati-*headers) - Run
brightdata-debug-bundleto create diagnostic package - Check https://status.brightdata.com for outages
- Contact support with zone name, error headers, and timestamps
Resources
Next Steps
For comprehensive debugging, see brightdata-debug-bundle.
04 同仓库更多 Skills
zustand-store-creator
Create zustand store creator operations. Auto-activating skill for Frontend Development. Triggers on: zustand store creator, zustand store creator Part of the Frontend Development skill category. Use when working with zustand store creator functionality. Trigger with phrases like "zustand store creator", "zustand creator", "zustand".
zero-trust-config-helper
Configure with zero trust config helper operations. Auto-activating skill for Security Advanced. Triggers on: zero trust config helper, zero trust config helper Part of the Security Advanced skill category. Use when configuring systems or services. Trigger with phrases like "zero trust config helper", "zero helper", "zero".
zapier-integration-helper
Assist with zapier integration helper operations. Auto-activating skill for Business Automation. Triggers on: zapier integration helper, zapier integration helper Part of the Business Automation skill category. Use when working with APIs or building integrations. Trigger with phrases like "zapier integration helper", "zapier helper", "zapier".
yaml-config-validator
Validate yaml config validator operations. Auto-activating skill for DevOps Basics. Triggers on: yaml config validator, yaml config validator Part of the DevOps Basics skill category. Use when configuring systems or services. Trigger with phrases like "yaml config validator", "yaml validator", "yaml".
xvary-stock-research
Thesis-driven equity analysis from public SEC EDGAR and market data; /analyze, /score, /compare workflows with bundled Python tools (Claude Code, Cursor, Codex).
xss-vulnerability-scanner
Scan xss vulnerability scanner operations. Auto-activating skill for Security Fundamentals. Triggers on: xss vulnerability scanner, xss vulnerability scanner Part of the Security Fundamentals skill category. Use when working with xss vulnerability scanner functionality. Trigger with phrases like "xss vulnerability scanner", "xss scanner", "xss".