Troubleshooting Guide

Fresh

Session Issues

Session Creation Fails

Symptom	Cause	Solution
401 Unauthorized	Invalid API key	Regenerate key in Settings > API Keys
429 Rate Limited	Too many requests	Check plan limits, implement backoff
Session limit reached	Max concurrent sessions	Release unused sessions, upgrade plan

Session Timeouts

// Default timeout is 5 minutes (300000ms)
// Increase for long-running tasks
const session = await client.sessions.create({
  timeout: 1800000  // 30 minutes
});

Plan	Max Session Time
Hobby	15 minutes
Starter	30 minutes
Developer	1 hour
Pro	24 hours

Orphaned Sessions

// Release all active sessions at once
await client.sessions.releaseAll();

Connection Issues

WebSocket Connection Failed

Error: WebSocket connection to 'wss://connect.steel.dev' failed

Solutions:

1. Verify API key is correct
2. Check session ID is valid UUID format
3. Ensure session is in "Live" state
4. Check network/firewall allows WebSocket connections

Playwright Connection Issues

// Ensure you use existing context, don't create new
const page = browser.contexts()[0].pages()[0];  // Correct
// const page = await browser.newPage();  // Wrong - won't be recorded

Proxy Issues

ERR_TUNNEL_CONNECTION_FAILED

This is normal and transient. Solutions:

1. Retry the request (Steel auto-rotates IP)
2. Change geographic region
3. If using BYOP, verify proxy server is online

ERR_PROXY_CONNECTION_FAILED

1. Check BYOP proxy credentials
2. Verify proxy server is accessible
3. Try different proxy format (http vs socks5)

Site Blocking Despite Proxy

1. Try different geographic region
2. Use BYOP with specialized provider
3. Some sites are on compliance blocklists - contact Steel support

CAPTCHA Issues

CAPTCHAs Not Being Solved

1. Verify solveCaptcha: true is set
2. Check plan supports CAPTCHA solving (Developer+)
3. Verify CAPTCHA type is supported
4. Increase timeout for CAPTCHA-heavy sites

Repeated CAPTCHAs

1. Enable residential proxy: useProxy: true
2. Add natural delays between actions
3. Vary request patterns
4. Use browser profiles for session continuity

Authentication Issues

Credentials Not Injecting

1. Verify origin matches exactly
2. Check namespace matches between credential and session
3. Wait at least 2 seconds after navigation
4. Check credential was created successfully

Auth Context Not Working

1. Capture context before releasing session
2. Verify target site uses cookie/JWT auth
3. Check if tokens have expired
4. Consider using Profiles API for more robust persistence

Profile in FAILED State

1. Profile exceeded 300 MB limit
2. Create a new profile with less data
3. Use auth context as alternative

Docker / Self-Hosting Issues

Chrome Won't Start

# Check container logs
docker logs steel-browser_api_1

# Common issues:
# - Insufficient memory (need 4GB+)
# - ARM architecture (use ARM images)
# - Missing shared libraries

UI Can't Connect to API

# Verify both containers running
docker ps

# Check API health
curl http://localhost:3000/api/health

# Check network connectivity
docker exec steel-browser_ui_1 curl http://api:3000/api/health

CLI Issues

Command Not Found

# Reinstall globally
npm install -g @steel-dev/cli

# Or use npx
npx @steel-dev/cli run playwright

Authentication Failed

steel logout
steel login

Template Errors

steel cache --clean
steel forge playwright

Getting Help

• Discord: discord.gg/steel-dev (#help channel)
• GitHub: github.com/steel-dev
• Docs: docs.steel.dev
• CLI: Run steel support to join Discord