Overview
This guide covers common issues you may encounter when installing, configuring, or running APITHON, along with their solutions. Issues are organized by category for easy navigation.Installation Issues
Playwright Installation Fails
Error: playwright install chromium fails
Error: playwright install chromium fails
Error: ModuleNotFoundError: No module named 'playwright'
Error: ModuleNotFoundError: No module named 'playwright'
Error: curl_cffi import fails
Error: curl_cffi import fails
curl_cffi is essential for Chrome impersonation (impersonate="chrome120" at apithon.py:123)Error: Flask import fails
Error: Flask import fails
Browser Automation Issues
Headless Mode Problems
Browser doesn't open (stuck at synchronization)
Browser doesn't open (stuck at synchronization)
headless=False (apithon.py:63):- Check system dependencies (see Playwright installation section)
- Verify display server (Linux)
- Try with slow_mo (debugging)
Error: Playwright timeout waiting for selector
Error: Playwright timeout waiting for selector
apithon.py:89)Why this happens:- Target site has a different UI structure
- Page loaded slowly
- Captcha or additional verification required
apithon.py:88-94Action required:- Wait for the browser window to fully load
- Manually type a message (anything, even ”.”) and press Enter
- The protocol sniffer will capture the request
- Once captured, the message ”[+] PROTOCOLO CAPTURADO” will appear
Browser closes immediately after opening
Browser closes immediately after opening
apithon.py:96-97Debug:
Add logging before line 96:status_ready is True but you didn’t send a message, the protocol sniffer pattern might have false-positive matched. Review the regex patterns at apithon.py:72-79.Cookie and Session Capture
Error: Protocol never gets captured (hangs forever)
Error: Protocol never gets captured (hangs forever)
- Browser opens successfully
- You manually send a message
- Terminal never shows ”[+] PROTOCOLO CAPTURADO”
- Hangs at
while not SESS["status_ready"]
StreamGenerate requestsDiagnosis:Add debug logging to the sniffer (apithon.py:67):- Wrong target URL: The service doesn’t use the expected protocol
- Changed API endpoint: Service updated their backend structure
- Request method mismatch: Service uses GET instead of POST
- Open browser DevTools (F12) manually on the target site
- Go to Network tab
- Send a message
- Look for the actual API endpoint being called
- Update the pattern in
apithon.py:68:
Error: Cookies not captured correctly
Error: Cookies not captured correctly
API Request Errors
401 Unauthorized
Error: Gateway returns 401 Unauthorized
Error: Gateway returns 401 Unauthorized
Backend returns 401 (target service unauthorized)
Backend returns 401 (target service unauthorized)
Empty or Invalid Responses
Response: 'Aviso: Flujo de datos vacío'
Response: 'Aviso: Flujo de datos vacío'
apithon.py:124-127- Add debug logging to see the raw response:
- Check if the response format changed
- Inspect the actual response structure from the target service
- Update regex pattern: The service might have changed response format
- Check for errors in response: Look for error messages in
r.text - Verify request payload: The
inner_structureformat might be incorrect for this service
Error: 'NoneType' object error in protocol execution
Error: 'NoneType' object error in protocol execution
NoneDiagnosis:None, the protocol wasn’t captured correctly:- Restart APITHON
- Ensure you send a message in the browser that triggers a StreamGenerate request
- Wait for the ”[+] PROTOCOLO CAPTURADO” message before proceeding
Error: Connection timeout or refused
Error: Connection timeout or refused
- Target service is down
- Network connectivity issues
- Firewall blocking outbound connections
- VPN/proxy interference
Platform-Specific Issues
Windows
PowerShell: curl command fails with JSON parse error
PowerShell: curl command fails with JSON parse error
curl to Invoke-WebRequest, which has different syntaxSolution:
Use curl.exe explicitly (as shown in the APITHON tutorial):apithon.py:149-151)CMD: Escaping issues with quotes
CMD: Escaping issues with quotes
apithon.py:153-154Error: 'clear' is not recognized (on startup)
Error: 'clear' is not recognized (on startup)
apithon.py:40-41If you still see this error, your Python environment is misdetecting the OS. This is cosmetic and won’t affect functionality.Linux
Error: Permission denied on port 5000
Error: Permission denied on port 5000
Error: Cannot connect to X display
Error: Cannot connect to X display
macOS
Error: Browser fails to launch (macOS specific)
Error: Browser fails to launch (macOS specific)
- Allow in System Preferences:
- System Preferences → Security & Privacy
- Look for message about blocked Chromium
- Click “Open Anyway”
- Grant accessibility permissions:
- System Preferences → Security & Privacy → Privacy → Accessibility
- Add Terminal or your Python IDE to the list
- Disable Gatekeeper temporarily (not recommended):
Connection and Network Errors
Error: Connection refused when accessing localhost
Error: Connection refused when accessing localhost
-
Check if Flask is running:
-
Verify you selected Gateway Mode:
- Did you choose Option 1 (Gateway) or Option 2 (Chat)?
- Gateway mode prints: “[MANTENIENDO PASARELA… Ctrl+C para cerrar]”
- Chat mode shows: ”[+] MODO CHAT LLM ACTIVADO”
- If in Chat mode, restart and select Option 1
- If gateway appears to be running but port isn’t listening, check for error messages in the terminal
Error: Address already in use
Error: Address already in use
LAN access fails (connection timeout)
LAN access fails (connection timeout)
Verify LAN mode is active
192.168.1.45), not 127.0.0.1.Test from host machine first
Check firewall rules
Protocol and Session Issues
Error: Internal context not captured
Error: Internal context not captured
SESS["internal_context"]isNone- Protocol appears captured but requests fail
apithon.py:72-73- Add debug logging to protocol_sniffer:
- Look for the context token pattern in the output
- Adjust the regex if the format changed
Error: Build ID or Session ID missing
Error: Build ID or Session ID missing
SESS["build_id"]orSESS["session_id"]isNone- Requests fail with malformed URLs
apithon.py:73-79Session expires during usage
Session expires during usage
- Works initially
- After some time (minutes/hours), all requests return 401 or empty responses
- Short-term: Restart APITHON and re-authenticate
- Long-term: Implement cookie refresh logic
Performance and Stability
Slow response times
Slow response times
- Requests take 10+ seconds to complete
- Gateway becomes unresponsive
- Target service is slow
- Network latency
- curl_cffi overhead
- Flask debug mode (already disabled in APITHON)
- Use Chat mode for faster direct responses (no HTTP overhead)
- Check network connectivity between host and target service
- Consider implementing request timeout:
Memory usage grows over time
Memory usage grows over time
- APITHON consumes increasing memory
- System becomes sluggish after running for hours
Concurrent requests fail or queue
Concurrent requests fail or queue
- Multiple simultaneous requests cause delays
- Some requests timeout
apithon.py:167 - No threading enabled by defaultSolutions:-
Enable Flask threading:
-
Use production server:
Debug Mode and Logging
Enable Comprehensive Debugging
Getting Help
Check Logs
Verify Dependencies
Test Connectivity
Simplify Configuration
- All dependencies installed (
flask,playwright,curl_cffi) - Chromium browser installed (
playwright install chromium) - Target URL is accessible in a regular browser
- You’re logged into the target service before running APITHON
- Firewall allows connections on port 5000 (LAN mode)
- API key matches in both client and server (
UnHackerEnCapital) - Session was successfully synchronized (saw ”[+] PROTOCOLO CAPTURADO”)
- Using correct network configuration (L for local, N for LAN)