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.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
- Check current tab title in targets.json:
- Manually verify the actual tab title:
- Check server console for screen capture errors
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:cuddlephish.html and broadcast.html:
- Install coturn:
- Configure coturn (
/etc/turnserver.conf):
- 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
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: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
- Variable substitution failed in HTML (CLIENT_IP, TARGET_ID, PAGE_TITLE)
- Check server route handlers for proper string replacement
- WebRTC not supported in browser
- STUN/TURN configuration incorrect
- ICE gathering failed
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:- Puppeteer failed to launch Chrome
- Missing dependencies
- Xvfb failed to start
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
checking→connected= Successchecking→failed= 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:- Check your public IP:
- Verify config.json:
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
- Check for victim connections in server logs
- Verify socket_key matches between config.json and admin.html
- Check browser console on admin page for socket errors
Issue: Thumbnails Not Updating
Symptom: Browser tiles appear but thumbnails are black or frozen Root Cause:- Browser instance crashed
- Canvas capture failing
- WebSocket disconnected
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:- 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
- 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
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
- Navigate to chrome://extensions/
- Toggle extension off and back on
- Refresh target page
Installation Issues
Issue: npm install Fails
Symptom: Errors during npm install Common Errors: “puppeteer download failed”Issue: Docker Build Fails
Symptom: Caddy Docker build errors Solution: Check Docker installation: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:Getting Help
If issues persist after following this guide:-
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
-
Check existing issues:
- Review GitHub issues: https://github.com/fkasler/cuddlephish/issues
- Search for your specific error message
-
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.