Skip to content

Troubleshooting Guide

This guide covers common issues that may arise during the installation, configuration, and operation of Champa Intelligence, along with their solutions.

Installation & Startup Issues

Issue: The champa-intelligence container fails to start with a database connection error.

Log Message: psycopg2.OperationalError: could not connect to server: Connection refused

Causes & Solutions:

  1. Incorrect Database Credentials: Double-check the DB_HOST, DB_PORT, DB_USER, DB_NAME, and DB_PASSWORD environment variables in your .env file.
  2. Network Issues: Ensure the Champa Intelligence container can reach the database host. If using Docker Compose, make sure both containers are on the same champa-network. You can test connectivity from within the container: 
    docker exec -it champa-intelligence bash
# Inside the container:
apk add --no-cache postgresql-client
psql -h <DB_HOST> -p <DB_PORT> -U <DB_USER> -d <DB_NAME>
  3. Firewall: Check if a firewall on the database server is blocking connections from the application host.

Issue: The container starts, but the web UI shows a "502 Bad Gateway" error (when behind a reverse proxy like Nginx).

Causes & Solutions:

  1. Gunicorn Not Running: Check the container logs (docker logs champa-intelligence) to see if the Gunicorn process started correctly. Look for Python errors.
  2. Incorrect Proxy Configuration: Ensure your Nginx or other reverse proxy is correctly forwarding requests to the container's exposed port (e.g., proxy_pass http://localhost:8088;).
  3. Container Health: The container might be stuck in a restart loop. Check docker ps to see its status and uptime.

Application & UI Issues

Issue: The Portfolio or Process Intelligence Dashboard is empty or shows loading spinners indefinitely.

Causes & Solutions:

  1. Database Read Permissions: This is the most common cause. The database user (DB_USER) must have SELECT permissions on all act_* tables in the Camunda database schema. Grant read access to your user.
  2. API Errors: Open your browser's developer tools (F12) and check the Network tab. Look for failed API requests (e.g., to /portfolio/api/overview). The response body of the failed request will often contain a specific error message.
  3. Cache Issues: The Redis cache might contain stale or corrupted data.
    • Solution: Use the admin interface (Admin -> Cache Management) to clear the cache, or make a POST request to /api/cache/clear with an admin token.

Issue: AI Analysis fails with an "API features are not configured" error.

Cause: The GOOGLE_API_KEY environment variable is either not set or is invalid.

Solution:

  1. Ensure the GOOGLE_API_KEY is correctly set in your .env file.
  2. Verify that the API key is enabled in your Google Cloud project and has the "Generative Language API" enabled.
  3. Test the key directly from the server to rule out network issues: 
    curl -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=YOUR_API_KEY"

Issue: Login fails with "Invalid credentials" even with the correct password.

Causes & Solutions:

  1. Account Locked: The user may have too many failed login attempts. By default, the account is locked for 15 minutes. Check the application logs for messages about account locking.
  2. User Deactivated: An administrator may have deactivated the user account.
  3. Database Sync Issue: In rare cases, the user data in the champa_system database could be out of sync. Contact an administrator to verify the user's status.

Performance Issues

Issue: Dashboards are loading very slowly.

Causes & Solutions:

  1. Redis Disabled or Unreachable: If Redis is down, the application will fall back to direct database queries for everything, which is much slower. Check the status of the champa-redis container and the application logs for Redis connection errors.
  2. Slow Database Queries: The underlying Camunda database may be under heavy load or have poorly optimized queries.
    • Solution: Use the Health Monitoring page to check DB Latency and look for Slow Queries. Work with your DBA to optimize the database performance.
  3. Large Data Volume: If you are analyzing a very long time range, the queries will naturally be slower.
    • Solution: Reduce the time range for your analysis on the Process Intelligence Dashboard.

Logging and Diagnostics

Viewing Logs

The most important tool for troubleshooting is the application log.

  • Docker: 
    # View live logs
docker logs -f champa-intelligence

# View last 500 lines
docker logs --tail 500 champa-intelligence

Log Levels

For more detailed diagnostics, you can change the log level.

  • In .env file: Set LOG_LEVEL=DEBUG.
  • Restart the application container for the change to take effect.
  • DEBUG level will log detailed information, including individual database queries, which can be very helpful for diagnosing issues. Do not leave DEBUG enabled in production for extended periods, as it can generate large log files.