Claude Code: Improve defensive .env handling with robust error logging

- Add hardcoded skeleton fallback in env_init.py with safe defaults
- Implement pure-Python .env parsing (no python-dotenv dependency)
- Add explicit error logging for configuration failures
- Ensure critical vars (OPENCLAW_DATA_DIR, PORT, WORKER_MODE) have safe defaults
- Improve brain_minimal.py with better fallback handling and status logging

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

brain_minimal.py

@@ -25,37 +25,56 @@ from threading import Thread, Event
 # CRITICAL: Defensive .env initialization before any other imports
 # This prevents FileNotFoundError if brain_minimal.py runs before entrypoint.sh
 _fallback_mode = False
+_init_success = False
+
+# Ensure /app is in path for utils import
+if "/app" not in sys.path:
+    sys.path.insert(0, "/app")
+
+# Try to import and run env_init
 try:
-    # Ensure /app is in path for utils import
-    if "/app" not in sys.path:
-        sys.path.insert(0, "/app")
+    from utils.env_init import init_env
+    _init_success = init_env()
+    if not _init_success:
+        logging.basicConfig(level=logging.WARNING)
+        logging.warning("[BRAIN_MINIMAL] env_init returned False - using emergency defaults")
+        _fallback_mode = True
+except ImportError as e:
+    # If utils.env_init is not available, use emergency fallback
+    logging.basicConfig(level=logging.WARNING)
+    logging.error(f"[BRAIN_MINIMAL] Failed to import env_init: {e}")
+    logging.warning("[BRAIN_MINIMAL] Using emergency .env fallback (manual initialization)")
+    _fallback_mode = True
+
+    # Manual fallback: create .env if missing
+    env_file = Path("/app/.env")
+    if not env_file.exists():
+        env_example = Path("/app/.env.example")
+        if env_example.exists():
+            import shutil
+            shutil.copy(env_example, env_file)
+            logging.warning("[BRAIN_MINIMAL] .env not found - copied from .env.example (emergency fallback)")
+        else:
+            # Create .env with critical defaults
+            with open(env_file, "w") as f:
+                f.write("# Emergency fallback .env\n")
+                f.write("OPENCLAW_DATA_DIR=/data\n")
+                f.write("PORT=7860\n")
+                f.write("WORKER_MODE=auto\n")
+            logging.warning("[BRAIN_MINIMAL] .env.example not found - created .env with safe defaults (emergency fallback)")
 
-    # Try to import and run env_init
-    try:
-        from utils.env_init import init_env
-        init_env()
-    except ImportError:
-        # If utils.env_init is not available, create .env directly
-        env_file = Path("/app/.env")
-        if not env_file.exists():
-            env_example = Path("/app/.env.example")
-            if env_example.exists():
-                import shutil
-                shutil.copy(env_example, env_file)
-                logging.basicConfig(level=logging.INFO)
-                logging.warning("[BRAIN_MINIMAL] .env not found - copied from .env.example (fallback mode)")
-                _fallback_mode = True
-            else:
-                env_file.touch()
-                logging.basicConfig(level=logging.INFO)
-                logging.warning("[BRAIN_MINIMAL] .env.example not found - created empty .env (fallback mode)")
-                _fallback_mode = True
 except Exception as e:
     # Don't crash on .env init errors - log warning and continue
-    logging.basicConfig(level=logging.INFO)
-    logging.warning(f"[BRAIN_MINIMAL] .env initialization failed (using safe defaults): {e}")
+    logging.basicConfig(level=logging.WARNING)
+    logging.error(f"[BRAIN_MINIMAL] .env initialization failed: {type(e).__name__}: {e}")
+    logging.warning("[BRAIN_MINIMAL] Using emergency safe defaults")
     _fallback_mode = True
 
+    # Set emergency defaults directly
+    os.environ.setdefault("OPENCLAW_DATA_DIR", "/data")
+    os.environ.setdefault("PORT", "7860")
+    os.environ.setdefault("WORKER_MODE", "auto")
+
 # Configure logging
 logging.basicConfig(
     level=logging.INFO,
@@ -64,9 +83,13 @@ logging.basicConfig(
 )
 logger = logging.getLogger(__name__)
 
-# Log if fallback mode is active
-if _fallback_mode:
-    logger.warning("[BRAIN_MINIMAL] FALLBACK MODE ACTIVE - .env handling may be incomplete")
+# Log initialization status
+if _init_success:
+    logger.info("[BRAIN_MINIMAL] Environment initialized successfully via env_init")
+elif _fallback_mode:
+    logger.warning("[BRAIN_MINIMAL] FALLBACK MODE ACTIVE - .env handling used emergency defaults")
+else:
+    logger.warning("[BRAIN_MINIMAL] Environment status unknown - proceeding with caution")
 
 # Global shutdown flag
 _shutdown_event = Event()

utils/env_init.py

@@ -2,8 +2,10 @@
 """
 Environment initialization utility for HuggingClaw Cain.
 
-Ensures .env file exists with fallback to .env.example.
+Ensures .env file exists with fallback to .env.example or hardcoded skeleton.
 This prevents FileNotFoundError when Python modules load before entrypoint.sh runs.
+
+Provides robust dotenv loading with safe defaults for critical variables.
 """
 import os
 import logging
@@ -16,18 +18,67 @@ _APP_DIR = Path("/app")
 _ENV_FILE = _APP_DIR / ".env"
 _ENV_EXAMPLE = _APP_DIR / ".env.example"
 
+# Safe defaults for critical variables - these allow Cain to start with partial config
+_CRITICAL_DEFAULTS = {
+    # Data persistence defaults
+    "OPENCLAW_DATA_DIR": "/data",
+    "OPENCLAW_HOME": "/data/.openclaw",
+    "OPENCLAW_STATE_DIR": "/data/.openclaw",
+
+    # Server defaults
+    "PORT": "7860",
+    "WORKER_MODE": "auto",
+    "OPENCLAW_PASSWORD": "huggingclaw",
+
+    # Sync defaults
+    "SYNC_INTERVAL": "60",
+    "AUTO_CREATE_DATASET": "false",
+
+    # LLM defaults (empty - must be set for AI to work)
+    "OPENAI_API_KEY": "",
+    "OPENROUTER_API_KEY": "",
+    "OPENCLAW_DEFAULT_MODEL": "",
+
+    # HuggingFace defaults (empty - must be set for data sync to work)
+    "HF_TOKEN": "",
+    "OPENCLAW_DATASET_REPO": "",
+    "SPACE_ID": "tao-shen/HuggingClaw-Cain",
+}
+
+
+def _get_env_skeleton() -> str:
+    """
+    Return a hardcoded .env skeleton with safe defaults.
+    This is the ultimate fallback if .env.example is missing.
+    """
+    lines = [
+        "# HuggingClaw Cain - Auto-generated .env skeleton",
+        "# Generated because .env.example was not found",
+        "",
+    ]
+    for key, value in _CRITICAL_DEFAULTS.items():
+        if value:  # Only include non-empty defaults
+            lines.append(f"{key}={value}")
+        else:
+            lines.append(f"{key}=")  # Include empty key as placeholder
+    return "\n".join(lines) + "\n"
+
 
 def _ensure_env_file() -> bool:
     """
-    Ensure .env file exists, using .env.example as fallback.
+    Ensure .env file exists, using .env.example as fallback,
+    then hardcoded skeleton as ultimate fallback.
 
     Returns:
         True if .env exists or was created, False otherwise.
     """
     # If .env already exists, we're done
     if _ENV_FILE.exists():
+        logger.debug("[ENV_INIT] .env already exists")
         return True
 
+    logger.warning("[ENV_INIT] .env missing - creating fallback .env file")
+
     # Try to copy from .env.example
     if _ENV_EXAMPLE.exists():
         try:
@@ -52,43 +103,110 @@ def _ensure_env_file() -> bool:
                 logger.info(f"[ENV_INIT] Created .env from .env.example ({len(lines)} variables)")
                 return True
             else:
-                # No valid lines found, create empty .env
-                _ENV_FILE.touch()
-                logger.info("[ENV_INIT] Created empty .env (no valid vars in .env.example)")
-                return True
+                # No valid lines found, use skeleton
+                logger.warning("[ENV_INIT] No valid vars in .env.example - using skeleton fallback")
 
         except Exception as e:
             logger.warning(f"[ENV_INIT] Failed to create .env from .env.example: {e}")
-            # Create empty .env as last resort
-            try:
-                _ENV_FILE.touch()
-                logger.info("[ENV_INIT] Created empty .env as fallback")
-                return True
-            except Exception:
-                logger.error("[ENV_INIT] Failed to create .env file")
-                return False
-    else:
-        # .env.example doesn't exist, create empty .env
-        try:
-            _ENV_FILE.touch()
-            logger.info("[ENV_INIT] Created empty .env (.env.example not found)")
-            return True
-        except Exception as e:
-            logger.error(f"[ENV_INIT] Failed to create .env: {e}")
-            return False
+
+    # .env.example missing or failed - use hardcoded skeleton
+    try:
+        skeleton = _get_env_skeleton()
+        with open(_ENV_FILE, "w") as f:
+            f.write(skeleton)
+        logger.warning("[ENV_INIT] Created .env from hardcoded skeleton (safe defaults applied)")
+        return True
+    except Exception as e:
+        logger.error(f"[ENV_INIT] Failed to create .env from skeleton: {e}")
+        return False
 
 
-def init_env():
+def _load_env_file() -> bool:
     """
-    Initialize environment - call this at application startup.
+    Load environment variables from .env file using pure Python.
+    Falls back to safe defaults if loading fails.
 
-    This ensures .env exists before any code tries to load environment variables.
-    Safe to call multiple times.
+    Returns:
+        True if loading succeeded or defaults were applied, False on critical failure.
     """
     if not _ENV_FILE.exists():
-        logger.info("[ENV_INIT] .env missing, initializing...")
-        _ensure_env_file()
-    return True
+        logger.error("[ENV_INIT] Cannot load .env - file does not exist")
+        return False
+
+    try:
+        # Parse .env file manually (no python-dotenv dependency)
+        with open(_ENV_FILE, "r") as f:
+            for line in f:
+                line = line.strip()
+                # Skip empty lines and comments
+                if not line or line.startswith("#"):
+                    continue
+                # Parse VAR=value lines
+                if "=" in line:
+                    key, value = line.split("=", 1)
+                    key = key.strip()
+                    value = value.strip()
+                    # Only set if not already in environment (system vars take precedence)
+                    if key not in os.environ:
+                        os.environ[key] = value
+
+        logger.info("[ENV_INIT] Loaded environment variables from .env")
+        return True
+
+    except Exception as e:
+        logger.error(f"[ENV_INIT] Failed to load .env file: {e}")
+        logger.warning("[ENV_INIT] Applying safe defaults for critical variables")
+        # Apply safe defaults as fallback
+        for key, value in _CRITICAL_DEFAULTS.items():
+            if key not in os.environ:
+                os.environ[key] = value
+        return True  # Still return True since we applied defaults
+
+
+def init_env() -> bool:
+    """
+    Initialize environment - call this at application startup.
+
+    This ensures .env exists and is loaded with safe defaults.
+    Safe to call multiple times (idempotent).
+
+    Returns:
+        True if initialization succeeded, False otherwise.
+    """
+    try:
+        # Step 1: Ensure .env file exists
+        if not _ENV_FILE.exists():
+            logger.info("[ENV_INIT] .env missing, initializing...")
+            if not _ensure_env_file():
+                logger.error("[ENV_INIT] Failed to create .env file")
+
+        # Step 2: Load environment variables
+        if _ENV_FILE.exists():
+            if not _load_env_file():
+                logger.warning("[ENV_INIT] .env load failed, but safe defaults applied")
+
+        # Step 3: Verify critical variables have values (log warnings if missing)
+        _missing_critical = []
+        _optional_critical = ["HF_TOKEN", "OPENCLAW_DATASET_REPO", "OPENAI_API_KEY", "OPENROUTER_API_KEY"]
+        for key in _optional_critical:
+            if not os.environ.get(key):
+                _missing_critical.append(key)
+
+        if _missing_critical:
+            logger.warning(f"[ENV_INIT] Optional variables not set (features may be limited): {', '.join(_missing_critical)}")
+
+        # Log successful initialization
+        logger.info("[ENV_INIT] Environment initialization complete")
+        return True
+
+    except Exception as e:
+        logger.error(f"[ENV_INIT] Critical error during initialization: {e}")
+        logger.error("[ENV_INIT] Applying emergency safe defaults")
+        # Emergency fallback - set critical defaults directly
+        for key, value in _CRITICAL_DEFAULTS.items():
+            if key not in os.environ:
+                os.environ[key] = value
+        return True  # Still return True to allow app to start
 
 
 # Auto-run on import (safe, idempotent)