brightdata-common-errors

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 <[e-mail]>
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:

# 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