Skip to main content

Blank Page Issues

The most frequently reported issue is victims seeing a blank white page instead of the video stream. This is a symptom with multiple possible root causes.
Do Not Open Generic Issues: “Blank page” is a symptom, not a specific issue. Follow the diagnostic steps below to identify the root cause before seeking support.

Diagnostic Workflow

Follow this systematic approach to diagnose blank page issues:
1

Verify HTML Loading

Check that cuddlephish.html is loading correctly
2

Check JavaScript Console

Open browser DevTools and look for JavaScript errors
3

Verify Tab Title Matching

Confirm the tab title matches the configured value
4

Test STUN Connectivity

Verify STUN server is reachable from both server and client
5

Review Server Logs

Check Node.js console for WebRTC negotiation messages
6

Test ICE Connectivity

Use external tools to verify NAT traversal capabilities

Issue 1: Tab Title Mismatch

Symptom: Blank page on victim side, no video stream Root Cause: The --auto-select-desktop-capture-source Chrome flag requires an exact match of the tab title. If the title doesn’t match, Chrome fails to select the tab for screen capture. Common Scenarios:
  • Target service uses special characters in tab title
  • Tab title changes after redirect
  • Dynamic tab titles that change during page load
Diagnosis:
  1. Check current tab title in targets.json:
  1. Manually verify the actual tab title:
  1. Check server console for screen capture errors
Solutions: Solution A: Update Tab Title If the title has changed, update targets.json:
Solution B: Use Partial Match You only need enough of the title for a unique match. Shorten the title to avoid special characters:
Solution C: Handle Redirects If the target redirects and changes title, modify index.js to wait longer or navigate to the post-redirect URL:

Issue 2: STUN Server Unreachable

Symptom: Blank page, no errors in JavaScript console, WebRTC negotiation fails Root Cause: The STUN server (stun.l.google.com:19302) is not accessible from server or client, preventing ICE candidate gathering. Diagnosis: Test STUN connectivity: From Server:
From Client: Use https://icetest.info/ to test WebRTC connectivity Review Server Logs: Look for ICE candidate messages:
If no candidates appear, STUN is failing. Solutions: Solution A: Alternative STUN Server Edit both cuddlephish.html and broadcast.html:
Solution B: Deploy TURN Server For maximum reliability, deploy a TURN server:
  1. Install coturn:
  1. Configure coturn (/etc/turnserver.conf):
  1. Update HTML files with TURN configuration:

Issue 3: Incompatible NAT Type

Symptom: WebRTC negotiation starts but connection never establishes Root Cause: Network uses Symmetric NAT, which is incompatible with STUN-based WebRTC connections. Diagnosis: Test NAT type using: https://icetest.info/ NAT Compatibility:
  • ✅ Full-cone NAT
  • ✅ Address-restricted-cone NAT
  • ✅ Port-restricted cone NAT
  • ❌ Symmetric NAT
Solution: Deploy and configure a TURN server (see Issue 2, Solution B). TURN relays traffic through the server, bypassing NAT traversal issues.

Issue 4: Caddy Blocking Requests

Symptom: 403 Forbidden error on victim page Root Cause: Caddy’s user-agent filtering blocking the request Diagnosis: Check Caddyfile for user-agent denylist:
Test with curl:
If 403, the user-agent is blocked. Solution: Temporarily disable filtering for testing:
Add legitimate user-agents to whitelist: Modify Caddyfile to only block truly malicious agents.

Issue 5: JavaScript Errors

Symptom: Browser console shows JavaScript errors Common Errors: “Socket connection failed”
  • Server not running on port 58082
  • Caddy not proxying correctly
  • Firewall blocking WebSocket connections
“Cannot read property of undefined”
  • Variable substitution failed in HTML (CLIENT_IP, TARGET_ID, PAGE_TITLE)
  • Check server route handlers for proper string replacement
“RTCPeerConnection failed”
  • WebRTC not supported in browser
  • STUN/TURN configuration incorrect
  • ICE gathering failed
Diagnosis: Open browser DevTools (F12) and check Console tab for errors. Solution: Review server logs alongside browser console to identify where the connection chain breaks:

Connection Flow Issues

Expected Log Sequence

When working properly, you should see this log pattern:

Issue: No “Socket connected” Message

Symptom: Server starts but no browser instance connects Diagnosis:
Root Cause:
  • Puppeteer failed to launch Chrome
  • Missing dependencies
  • Xvfb failed to start
Solution: Check for missing dependencies:
If Puppeteer fails, install missing libraries:

Issue: Victim Connects But No Video

Symptom: Admin interface shows session, but victim sees blank page Diagnosis Checklist:
  • Victim socket ID appears in server logs
  • video_stream_offer sent
  • video_stream_answer received
  • ICE candidates exchanged
  • Tab title matches configuration
  • STUN server reachable
Root Cause: Likely ICE negotiation failure after initial WebSocket connection. Solution: Enable verbose WebRTC logging in cuddlephish.html:
Monitor console for state transitions:
  • checkingconnected = Success
  • checkingfailed = ICE negotiation failed (STUN/TURN issue)

Admin Interface Issues

Issue: Cannot Access Admin Interface (403)

Symptom: 403 Forbidden when accessing /admin Root Cause: IP address not in admin_ips whitelist Diagnosis:
  1. Check your public IP:
  1. Verify config.json:
Solution: Add your IP to config.json:
Restart the server after configuration changes.
Local Testing: If testing locally without a reverse proxy, the X-Real-IP header won’t be set. You may need to modify index.js to allow localhost connections for testing.

Issue: Admin Interface Loads But No Sessions

Symptom: Admin page accessible but no browser thumbnails appear Root Cause:
  • No victims have connected yet
  • Socket authentication failed
  • Thumbnails not generating
Diagnosis:
  1. Check for victim connections in server logs
  2. Verify socket_key matches between config.json and admin.html
  3. Check browser console on admin page for socket errors
Solution: Test with a victim connection:
Check server logs for:
If no client_ip appears, the victim request isn’t reaching the server.

Issue: Thumbnails Not Updating

Symptom: Browser tiles appear but thumbnails are black or frozen Root Cause:
  • Browser instance crashed
  • Canvas capture failing
  • WebSocket disconnected
Diagnosis: Check browser processes:
Should show Chrome processes equal to number of browser instances. Solution: Remove the stuck instance and allow victim to reconnect:
Check server logs for errors:

Performance Issues

Issue: High Memory Usage

Symptom: Server becomes slow or unresponsive with multiple victims Root Cause: Each browser instance consumes 500MB-1GB of RAM Solution: Monitor resource usage:
Recommendations:
  • Remove idle browser instances promptly
  • Size server based on expected concurrent users
  • Consider 2GB RAM per simultaneous victim
  • Monitor with htop during operations

Issue: Slow Video Streaming

Symptom: Video is choppy or has high latency Root Cause:
  • Server bandwidth limitations
  • CPU saturation from multiple browser instances
  • Network congestion
Solutions: Reduce video quality: Edit broadcast.html to lower frame rate:
Reduce thumbnail frequency: Edit broadcast.html to update thumbnails less frequently:
Scale server resources:
  • Upgrade to higher CPU count
  • Increase network bandwidth
  • Use dedicated server instead of VPS

Credential Extraction Issues

Issue: stealer.js Fails to Inject Cookies

Symptom: Browser opens but session not authenticated Root Cause:
  • Cookie domain mismatch
  • Cookie expired
  • SameSite restrictions
  • HTTPS required for Secure cookies
Diagnosis: Check extracted cookies:
Solution: Domain Mismatch: Ensure you’re navigating to correct domain that matches cookie:
Expired Cookies: Extract credentials immediately after authentication, before timeout. Secure Cookies: Always use HTTPS when replaying sessions with secure cookies.

Issue: Browser Extension Not Working

Symptom: Extension fails to extract or inject credentials Root Cause:
  • Debugger permission denied
  • Chrome version incompatibility
  • Target tab not active
Solution: Check permissions:
Reload extension:
  1. Navigate to chrome://extensions/
  2. Toggle extension off and back on
  3. Refresh target page
Ensure tab is active: Extension only works on the currently active tab.

Installation Issues

Issue: npm install Fails

Symptom: Errors during npm install Common Errors: “puppeteer download failed”
“node-gyp build failed”

Issue: Docker Build Fails

Symptom: Caddy Docker build errors Solution: Check Docker installation:
Verify Dockerfile syntax:
Try alternate DNS provider: If Gandi plugin fails, try Cloudflare:

Platform-Specific Issues

Kali Linux

Issue: Missing libraries for Chrome Solution: Uncomment the Kali-specific line in install_deps.sh:

ARM Architecture

Issue: Puppeteer fails to download Chromium Root Cause: Official Chromium builds not available for ARM Workaround:
Feature Loss: Using system Chromium on ARM loses puppeteer-extra stealth features and may be detectable as automation.

Getting Help

If issues persist after following this guide:
  1. Gather diagnostic information:
    • Server console output (full logs)
    • Browser DevTools console errors
    • Network tab showing WebSocket and WebRTC connections
    • config.json and targets.json (redact sensitive data)
    • Steps to consistently reproduce the issue
  2. Check existing issues:
  3. Open a detailed issue:
    • Provide all diagnostic information
    • Describe expected vs. actual behavior
    • Include reproduction steps
    • Specify your platform and versions
Issue Quality: Well-documented issues with reproduction steps receive faster responses than vague “it doesn’t work” reports.