Common Issues & Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• DEPLOYMENT.md
• backend/app.py
• pythonanywhere_wsgi.py
• wsgi.py
• static/index.html
• requirements.txt

This guide provides technical solutions and diagnostic steps for issues encountered during the deployment and operation of the Promethean Unified Platform. It specifically addresses environment configuration, connectivity with external services (Supabase and DeepSeek), and web server performance on PythonAnywhere.

The platform relies on a Flask backend interacting with a Supabase database and the DeepSeek LLM API. Errors typically manifest as HTTP 5xx status codes, module resolution failures, or frontend communication timeouts. Proper troubleshooting requires access to the PythonAnywhere error logs and verification of environment variables.

Sources: DEPLOYMENT.md:3-12, backend/app.py:12-14

Deployment & Server Connectivity

Deployment issues often stem from misconfigured WSGI files or incorrect directory paths on the hosting provider. The platform uses a specific WSGI entry point to bridge the Flask application with the web server.

502 Bad Gateway and Module Errors

A 502 Bad Gateway usually indicates the WSGI process failed to start. This is frequently caused by a missing .env file or an incorrectly configured virtual environment.

The diagram shows the initialization flow and common failure points during the WSGI startup sequence.
Sources: DEPLOYMENT.md:144-152, pythonanywhere_wsgi.py:6-21, wsgi.py:4-12

Troubleshooting Checklist for Server Errors

Issue	Potential Cause	Resolution
502 Bad Gateway	WSGI Config / Environment	Check /var/log/ error logs; verify .env readability.
ModuleNotFoundError	Virtualenv / Pathing	Run pip install -r requirements.txt; verify sys.path in WSGI.
Static Files Not Loading	Permissions / Paths	Set permissions to 755 (dirs) / 644 (files); check Web tab settings.
Permission Denied	File system access	Ensure the user has read access to the project folder.

Sources: DEPLOYMENT.md:144-165, requirements.txt:1-9

API & Integration Issues

The platform integrates with Supabase for data persistence and DeepSeek for AI responses. Connectivity issues with these services will cause the /api/chat and /api/consciousness/interact endpoints to fail.

DeepSeek LLM Connectivity

Errors during AI response generation typically occur in the generate_ai_response function when the DEEPSEEK_API_KEY is missing or invalid.

This sequence illustrates the fallback mechanism when the external LLM API is unavailable.
Sources: backend/app.py:122-160, DEPLOYMENT.md:154-158

Database Interaction Failures

The platform uses the supabase-py client. If the SUPABASE_URL or SUPABASE_ANON_KEY are incorrect, the application will throw exceptions during health checks or message logging.

• Symptom: /health or /api/chat returns HTTP 500.
• Log Entry: postgrest.exceptions.APIError or supabase.client.StorageException.
• Verification: Ensure environment variables in .env match the Supabase project dashboard.

Sources: backend/app.py:32-34, backend/app.py:43-62, DEPLOYMENT.md:175-180

Frontend & Client-Side Errors

The frontend communicates with the backend via the fetch API. Issues here are often related to security headers or network connectivity.

Security Header Conflicts

The backend enforces strict security headers via set_security_headers. If the Content Security Policy (CSP) is too restrictive, external scripts or inline styles may fail to load.

# backend/app.py:17-27
@app.after_request
def set_security_headers(response):
    response.headers['X-Content-Type-Options'] = 'nosniff'
    response.headers['X-Frame-Options'] = 'DENY'
    response.headers['X-XSS-Protection'] = '1; mode=block'
    response.headers['Content-Security-Policy'] = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'"
    return response

Sources: backend/app.py:17-27, DEPLOYMENT.md:126-133

UI State and API Errors

In static/index.html, the sendMessage() function handles API errors. If the backend returns a non-200 status code, the UI displays an error message to the user.

• Issue: Send button remains disabled.
• Cause: Javascript exception in the try...catch block of sendMessage().
• Fix: Check browser console for API error: [status] or network timeout.

Sources: static/index.html:242-263, static/index.html:270-280

Summary of Diagnostic Logs

For all issues, the primary source of truth is the PythonAnywhere log system.

Log Type	Location	Use Case
Error Log	/var/log/[username].pythonanywhere.com_error.log	Debugging Python exceptions and 5xx errors.
Access Log	/var/log/[username].pythonanywhere.com_access.log	Monitoring API traffic and 4xx status codes.
Server Log	/var/log/[username].pythonanywhere.com_server.log	Issues with the web server process itself.

Sources: DEPLOYMENT.md:167-170