Brightdata Common Errors

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-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:

# 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=1 for SERP API requests

X-Luminati-Error Headers

Bright Data returns error details in response headers:

Quick Diagnostic Commands

# Check Bright Data status
curl -s 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

1. Collect request/response headers (including X-Luminati-* headers)
2. Run brightdata-debug-bundle to create diagnostic package
3. Check for outages
4. Contact support with zone name, error headers, and timestamps

Resources

• Bright Data Error Reference
• Status Page
• Support Portal

Next Steps

For comprehensive debugging, see brightdata-debug-bundle.

Source: jeremylongshore/claude-code-plugins-plus-skills → skills/.curated/brightdata-common-errors/SKILL.md

Also appears in: jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/brightdata-pack/skills/brightdata-common-errors/SKILL.md