feat: Add DEBUG_MODE for troubleshooting configuration issues

- Add DEBUG_MODE option in .env to enable verbose logging
- Log .env file loading status and working directory
- Log all loaded configuration values at startup
- Add detailed logging for /api/config and /api/models endpoints
- Test Ollama connection at server startup
- Increase Ollama timeout from 5s to 10s
- Distinguish connection errors (ConnectionError, Timeout, etc.)

Helps diagnose issues like #84 where models or languages are not detected.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: hydropix

.env.example

@@ -42,4 +42,10 @@ SRT_MAX_CHARS_PER_BLOCK=500
 # This adds a discrete attribution to your translations (metadata for EPUB, footer for TXT, comment for SRT)
 # Please consider keeping this enabled to support the project and help others discover this free tool!
 # The signature is non-intrusive and placed at the end of files. Thank you for your support!
-SIGNATURE_ENABLED=true
+SIGNATURE_ENABLED=true
+
+# Debug Mode
+# Enable verbose logging for troubleshooting configuration and connection issues.
+# Set to 'true' to see detailed logs about .env loading, API calls, and configuration values.
+# Useful when models are not detected or languages are not applied correctly.
+DEBUG_MODE=false

src/api/blueprints/config_routes.py

@@ -3,6 +3,7 @@
 """
 import os
 import asyncio
+import logging
 import requests
 from flask import Blueprint, request, jsonify, send_from_directory
 
@@ -15,9 +16,15 @@
     MAX_TRANSLATION_ATTEMPTS,
     RETRY_DELAY_SECONDS,
     DEFAULT_SOURCE_LANGUAGE,
-    DEFAULT_TARGET_LANGUAGE
+    DEFAULT_TARGET_LANGUAGE,
+    DEBUG_MODE
 )
 
+# Setup logger for this module
+logger = logging.getLogger('config_routes')
+if DEBUG_MODE:
+    logger.setLevel(logging.DEBUG)
+
 
 def create_config_blueprint():
     """Create and configure the config blueprint"""
@@ -57,7 +64,7 @@ def get_default_config():
         """Get default configuration values"""
         gemini_api_key = os.getenv('GEMINI_API_KEY', '')
 
-        return jsonify({
+        config_response = {
             "api_endpoint": DEFAULT_OLLAMA_API_ENDPOINT,
             "default_model": DEFAULT_MODEL,
             "chunk_size": MAIN_LINES_PER_CHUNK,
@@ -69,7 +76,16 @@ def get_default_config():
             "gemini_api_key": gemini_api_key,
             "default_source_language": DEFAULT_SOURCE_LANGUAGE,
             "default_target_language": DEFAULT_TARGET_LANGUAGE
-        })
+        }
+
+        if DEBUG_MODE:
+            logger.debug(f"📤 /api/config response:")
+            logger.debug(f"   default_source_language: {DEFAULT_SOURCE_LANGUAGE}")
+            logger.debug(f"   default_target_language: {DEFAULT_TARGET_LANGUAGE}")
+            logger.debug(f"   api_endpoint: {DEFAULT_OLLAMA_API_ENDPOINT}")
+            logger.debug(f"   default_model: {DEFAULT_MODEL}")
+
+        return jsonify(config_response)
 
     def _get_gemini_models():
         """Get available models from Gemini API"""
@@ -124,25 +140,59 @@ def _get_ollama_models():
         """Get available models from Ollama API"""
         ollama_base_from_ui = request.args.get('api_endpoint', DEFAULT_OLLAMA_API_ENDPOINT)
 
+        if DEBUG_MODE:
+            logger.debug(f"📥 /api/models request for Ollama")
+            logger.debug(f"   api_endpoint from UI: {ollama_base_from_ui}")
+            logger.debug(f"   default endpoint: {DEFAULT_OLLAMA_API_ENDPOINT}")
+
         try:
             base_url = ollama_base_from_ui.split('/api/')[0]
             tags_url = f"{base_url}/api/tags"
-            response = requests.get(tags_url, timeout=5)
+
+            if DEBUG_MODE:
+                logger.debug(f"   Connecting to: {tags_url}")
+
+            response = requests.get(tags_url, timeout=10)  # Increased timeout from 5 to 10
+
+            if DEBUG_MODE:
+                logger.debug(f"   Response status: {response.status_code}")
 
             if response.status_code == 200:
                 data = response.json()
                 models_data = data.get('models', [])
                 model_names = [m.get('name') for m in models_data if m.get('name')]
 
+                if DEBUG_MODE:
+                    logger.debug(f"   Models found: {model_names}")
+
                 return jsonify({
                     "models": model_names,
                     "default": DEFAULT_MODEL if DEFAULT_MODEL in model_names else (model_names[0] if model_names else DEFAULT_MODEL),
                     "status": "ollama_connected",
                     "count": len(model_names)
                 })
+            else:
+                if DEBUG_MODE:
+                    logger.debug(f"   ❌ Non-200 response: {response.status_code}")
+                    logger.debug(f"   Response body: {response.text[:500]}")
+
+        except requests.exceptions.ConnectionError as e:
+            error_msg = f"Connection refused to {tags_url}. Is Ollama running?"
+            if DEBUG_MODE:
+                logger.debug(f"   ❌ ConnectionError: {e}")
+            print(f"❌ {error_msg}")
+        except requests.exceptions.Timeout as e:
+            error_msg = f"Timeout connecting to {tags_url} (10s)"
+            if DEBUG_MODE:
+                logger.debug(f"   ❌ Timeout: {e}")
+            print(f"❌ {error_msg}")
         except requests.exceptions.RequestException as e:
+            if DEBUG_MODE:
+                logger.debug(f"   ❌ RequestException: {type(e).__name__}: {e}")
             print(f"❌ Could not connect to Ollama at {ollama_base_from_ui}: {e}")
         except Exception as e:
+            if DEBUG_MODE:
+                logger.debug(f"   ❌ Unexpected error: {type(e).__name__}: {e}")
             print(f"❌ Error retrieving models from {ollama_base_from_ui}: {e}")
 
         return jsonify({

src/config.py

@@ -3,15 +3,32 @@
 """
 import os
 import sys
+import logging
 from pathlib import Path
 from dataclasses import dataclass
 from typing import Optional
 from dotenv import load_dotenv
 
+# Setup debug logger for configuration
+_config_logger = logging.getLogger('config')
+
+# Check for DEBUG_MODE early (before .env is loaded, check environment)
+_debug_mode = os.getenv('DEBUG_MODE', 'false').lower() == 'true'
+if _debug_mode:
+    logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    _config_logger.setLevel(logging.DEBUG)
+    _config_logger.debug("🔍 DEBUG_MODE enabled - verbose logging active")
+
 # Check if .env file exists and provide helpful guidance
 _env_file = Path('.env')
 _env_example = Path('.env.example')
 _env_exists = _env_file.exists()
+_cwd = Path.cwd()
+
+if _debug_mode:
+    _config_logger.debug(f"📁 Current working directory: {_cwd}")
+    _config_logger.debug(f"📁 Looking for .env at: {_env_file.absolute()}")
+    _config_logger.debug(f"📁 .env exists: {_env_exists}")
 
 if not _env_exists:
     print("\n" + "="*70)
@@ -51,7 +68,9 @@
         sys.exit(0)
 
 # Load .env file if it exists
-load_dotenv()
+_dotenv_result = load_dotenv()
+if _debug_mode:
+    _config_logger.debug(f"📁 load_dotenv() returned: {_dotenv_result}")
 
 # Load from environment variables with defaults
 API_ENDPOINT = os.getenv('API_ENDPOINT', 'http://localhost:11434/api/generate')
@@ -98,6 +117,28 @@
 HOST = os.getenv('HOST', '127.0.0.1')
 OUTPUT_DIR = os.getenv('OUTPUT_DIR', 'translated_files')
 
+# Debug mode (reload after .env is loaded)
+DEBUG_MODE = os.getenv('DEBUG_MODE', 'false').lower() == 'true'
+
+# Log loaded configuration in debug mode
+if DEBUG_MODE or _debug_mode:
+    _config_logger.setLevel(logging.DEBUG)
+    _config_logger.debug("="*60)
+    _config_logger.debug("📋 LOADED CONFIGURATION VALUES:")
+    _config_logger.debug("="*60)
+    _config_logger.debug(f"   API_ENDPOINT: {API_ENDPOINT}")
+    _config_logger.debug(f"   DEFAULT_MODEL: {DEFAULT_MODEL}")
+    _config_logger.debug(f"   LLM_PROVIDER: {LLM_PROVIDER}")
+    _config_logger.debug(f"   PORT: {PORT}")
+    _config_logger.debug(f"   HOST: {HOST}")
+    _config_logger.debug(f"   DEFAULT_SOURCE_LANGUAGE: {DEFAULT_SOURCE_LANGUAGE}")
+    _config_logger.debug(f"   DEFAULT_TARGET_LANGUAGE: {DEFAULT_TARGET_LANGUAGE}")
+    _config_logger.debug(f"   OLLAMA_NUM_CTX: {OLLAMA_NUM_CTX}")
+    _config_logger.debug(f"   REQUEST_TIMEOUT: {REQUEST_TIMEOUT}")
+    _config_logger.debug(f"   GEMINI_API_KEY: {'***' + GEMINI_API_KEY[-4:] if GEMINI_API_KEY else '(not set)'}")
+    _config_logger.debug(f"   OPENAI_API_KEY: {'***' + OPENAI_API_KEY[-4:] if OPENAI_API_KEY else '(not set)'}")
+    _config_logger.debug("="*60)
+
 # Translation tags - Improved for LLM clarity and reliability
 TRANSLATE_TAG_IN = "<TRANSLATION>"
 TRANSLATE_TAG_OUT = "</TRANSLATION>"

translation_api.py

@@ -120,6 +120,31 @@ def restore_incomplete_jobs():
 
 restore_incomplete_jobs()
 
+def test_ollama_connection():
+    """Test Ollama connection at startup and log result"""
+    import requests
+    try:
+        base_url = DEFAULT_OLLAMA_API_ENDPOINT.split('/api/')[0]
+        tags_url = f"{base_url}/api/tags"
+        logger.info(f"🔍 Testing Ollama connection at {tags_url}...")
+        response = requests.get(tags_url, timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            models = [m.get('name') for m in data.get('models', [])]
+            logger.info(f"✅ Ollama connected! Found {len(models)} model(s): {models}")
+            return True
+        else:
+            logger.warning(f"⚠️ Ollama returned status {response.status_code}")
+            return False
+    except requests.exceptions.ConnectionError:
+        logger.warning(f"⚠️ Cannot connect to Ollama at {base_url}")
+        logger.warning(f"   Make sure Ollama is running ('ollama serve')")
+        return False
+    except Exception as e:
+        logger.warning(f"⚠️ Ollama connection test failed: {e}")
+        return False
+
+
 if __name__ == '__main__':
     # Validate configuration before starting
     validate_configuration()
@@ -132,6 +157,11 @@ def restore_incomplete_jobs():
     logger.info(f"   - API: http://{HOST}:{PORT}/api/")
     logger.info(f"   - Health Check: http://{HOST}:{PORT}/api/health")
     logger.info(f"   - Supported formats: .txt, .epub, and .srt")
+    logger.info("")
+
+    # Test Ollama connection at startup
+    test_ollama_connection()
+
     logger.info("")
     logger.info("💡 Press Ctrl+C to stop the server")
     logger.info("")