Error Handling & Logging

Relevant source files

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

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

Introduction

The Promethean Unified Platform employs a centralized approach to error handling and logging, primarily focused on maintaining service availability and diagnostic visibility during production deployments on PythonAnywhere. The system integrates backend exception catching with frontend error surfacing to ensure that failures in the DeepSeek LLM integration or Supabase database operations are communicated to both the user and the system administrators.

Monitoring is primarily driven through PythonAnywhere's standard logging infrastructure, which captures access patterns, server-side errors, and WSGI-level issues. This ensures that the "transparent" nature of the AI system extends to its operational reliability and troubleshooting capabilities.
Sources: DEPLOYMENT.md:144-150, backend/app.py:108-112

Backend Error Handling

The Flask backend utilizes standard Python try-except blocks across all major API endpoints to prevent application crashes and provide meaningful JSON error responses to the client.

Exception Catching Logic

Each route, including /health, /api/consciousness/interact, and /api/chat, is wrapped in a high-level exception handler. When an error occurs—such as a database connection failure or an API timeout—the system catches the exception and returns a HTTP 500 status code with a JSON payload containing the error description.

The flow shows how exceptions are intercepted before they reach the WSGI server level, allowing the application to remain stable.
Sources: backend/app.py:53-61, backend/app.py:108-112

LLM Integration Fallbacks

The AI response generation logic includes specific handling for the DeepSeek API. If the DEEPSEEK_API_KEY is missing or the external API request fails, the system executes a fallback mechanism to return a predefined response rather than failing entirely.

Error Scenario	Handling Mechanism	Response Source
Missing API Key	Environment variable check	Local fallback string
API Status != 200	Conditional check on response.status_code	Local fallback string
General Exception	try-except block in generate_ai_response	Error string with exception detail

Sources: backend/app.py:115-147, DEPLOYMENT.md:131-135

Logging Infrastructure

Logging is stratified across different layers of the platform, from application-level event reporting to server-level access logs.

Server Logs

In the production environment (PythonAnywhere), three primary log files are maintained:

1. Error Log: Captures Python exceptions not caught by the application, WSGI configuration errors, and server-level crashes. Path: /var/log/yourusername.pythonanywhere.com_error.log.
2. Access Log: Records all incoming HTTP requests, including method, path, and status code. Used for monitoring API usage patterns.
3. Server Log: General logs from the PythonAnywhere infrastructure regarding the web app's lifecycle.

Sources: DEPLOYMENT.md:144-147

Application State Logging

The backend uses Supabase as a persistent log for user interactions. Every message processed through /api/chat or /health is logged into the chat_messages or interactions tables, providing a historical record of system activity and potential logic failures.
Sources: backend/app.py:91-105

Frontend Error Surfacing

The frontend interface in index.html includes mechanisms to handle and display errors encountered during asynchronous fetch operations.

User Feedback Flow

When the frontend communicates with /api/chat, it monitors the response status. If a network error occurs or the backend returns a non-OK status, the UI removes the "typing indicator" and appends an error message directly into the chat container to inform the user.

Configuration and Troubleshooting

Common errors and their resolutions are documented to facilitate rapid recovery during deployment.

Error	Source	Troubleshooting Step
502 Bad Gateway	WSGI / Server	Check PythonAnywhere error logs and wsgi.py paths.
ModuleNotFoundError	Environment	Verify virtualenv in pythonanywhere_wsgi.py and run pip install.
API Integration Error	External API	Verify DEEPSEEK_API_KEY in .env and check API credits.

Sources: DEPLOYMENT.md:126-142, pythonanywhere_wsgi.py:7-16

Summary

Error handling in the Promethean Unified Platform is designed for resilience. By combining granular try-except logic in backend/app.py, robust logging via PythonAnywhere, and real-time error surfacing in the index.html frontend, the system ensures that issues are caught, logged for developers, and explained to users without compromising the integrity of the unified consciousness platform.