feat(exceptions): enhance error handling and logging to give accurate login action feedback

Author: stickerdaniel

README.md

@@ -37,6 +37,17 @@ Suggest improvements for my CV to target this job posting https://www.linkedin.c
 > - **Recommended Jobs** (`get_recommended_jobs`): Selenium method compatibility issues
 > - **Company Profiles** (`get_company_profile`): Some companies can't be accessed / may return empty results (need further investigation)
 
+## 🛡️ Error Handling & Non-Interactive Mode
+
+**NEW**: Enhanced error handling for Docker and CI/CD environments!
+
+The server now provides detailed error information when login fails:
+- **Specific error types**: `credentials_not_found`, `invalid_credentials`, `captcha_required`, `two_factor_auth_required`, `rate_limit`
+- **Non-interactive mode**: Use `--no-setup` to skip all prompts (perfect for Docker)
+- **Structured responses**: Each error includes type, message, and resolution steps
+
+For detailed error handling documentation, see [ERROR_HANDLING.md](ERROR_HANDLING.md)
+
 ---
 
 ## 🐳 Docker Setup (Recommended - Universal)
@@ -57,7 +68,8 @@ Suggest improvements for my CV to target this job posting https://www.linkedin.c
         "run", "-i", "--rm",
         "-e", "LINKEDIN_EMAIL",
         "-e", "LINKEDIN_PASSWORD",
-        "stickerdaniel/linkedin-mcp-server"
+        "stickerdaniel/linkedin-mcp-server",
+        "--no-setup"
       ],
       "env": {
         "LINKEDIN_EMAIL": "your.email@example.com",
@@ -76,6 +88,7 @@ Suggest improvements for my CV to target this job posting https://www.linkedin.c
 - **Streamable HTTP**: For a web-based MCP server
 
 **CLI Options:**
+- `--no-setup` - Skip interactive prompts (required for Docker/non-interactive environments)
 - `--debug` - Enable detailed logging
 - `--no-lazy-init` - Login to LinkedIn immediately instead of waiting for the first tool call
 - `--transport {stdio,streamable-http}` - Set transport mode
@@ -90,7 +103,7 @@ docker run -i --rm \
   -e LINKEDIN_PASSWORD="your_password" \
   -p 8080:8080 \
   stickerdaniel/linkedin-mcp-server \
-  --transport streamable-http --host 0.0.0.0 --port 8080 --path /mcp
+  --no-setup --transport streamable-http --host 0.0.0.0 --port 8080 --path /mcp
 ```
 **Test with mcp inspector:**
 1. Install and run mcp inspector ```bunx @modelcontextprotocol/inspector```

linkedin_mcp_server/config/loaders.py

@@ -135,6 +135,9 @@ def load_from_args(config: AppConfig) -> AppConfig:
 
     if args.no_setup:
         config.server.setup = False
+        config.chrome.non_interactive = (
+            True  # Automatically set when --no-setup is used
+        )
 
     if args.no_lazy_init:
         config.server.lazy_init = False

linkedin_mcp_server/config/secrets.py

@@ -1,10 +1,11 @@
 # src/linkedin_mcp_server/config/secrets.py
 import logging
-from typing import Dict, Optional
+from typing import Dict
 
 import inquirer  # type: ignore
 
 from linkedin_mcp_server.config import get_config
+from linkedin_mcp_server.exceptions import CredentialsNotFoundError
 
 from .providers import (
     get_credentials_from_keyring,
@@ -15,7 +16,7 @@
 logger = logging.getLogger(__name__)
 
 
-def get_credentials() -> Optional[Dict[str, str]]:
+def get_credentials() -> Dict[str, str]:
     """Get LinkedIn credentials from config, keyring, or prompt."""
     config = get_config()
 
@@ -31,10 +32,12 @@ def get_credentials() -> Optional[Dict[str, str]]:
             print(f"Using LinkedIn credentials from {get_keyring_name()}")
             return {"email": credentials["email"], "password": credentials["password"]}
 
-    # If in non-interactive mode and no credentials found, return None
+    # If in non-interactive mode and no credentials found, raise error
     if config.chrome.non_interactive:
-        print("No credentials found in non-interactive mode")
-        return None
+        raise CredentialsNotFoundError(
+            "No LinkedIn credentials found. Please provide credentials via "
+            "environment variables (LINKEDIN_EMAIL, LINKEDIN_PASSWORD) or keyring."
+        )
 
     # Otherwise, prompt for credentials
     return prompt_for_credentials()

linkedin_mcp_server/drivers/chrome.py

@@ -18,6 +18,18 @@
 from linkedin_mcp_server.config import get_config
 from linkedin_mcp_server.config.providers import clear_credentials_from_keyring
 from linkedin_mcp_server.config.secrets import get_credentials
+from linkedin_scraper.exceptions import (
+    CaptchaRequiredError,
+    InvalidCredentialsError,
+    LoginTimeoutError,
+    RateLimitError,
+    SecurityChallengeError,
+    TwoFactorAuthError,
+)
+from linkedin_mcp_server.exceptions import (
+    CredentialsNotFoundError,
+    DriverInitializationError,
+)
 
 # Global driver storage to reuse sessions
 active_drivers: Dict[str, webdriver.Chrome] = {}
@@ -87,24 +99,41 @@ def get_or_create_driver() -> Optional[webdriver.Chrome]:
         driver.set_page_load_timeout(60)
 
         # Try to log in
-        if login_to_linkedin(driver):
-            print("Successfully logged in to LinkedIn")
-        elif config.chrome.non_interactive:
-            # In non-interactive mode, if login fails, return None
+        try:
+            if login_to_linkedin(driver):
+                print("Successfully logged in to LinkedIn")
+                active_drivers[session_id] = driver
+                return driver
+        except (
+            CaptchaRequiredError,
+            InvalidCredentialsError,
+            SecurityChallengeError,
+            TwoFactorAuthError,
+            RateLimitError,
+            LoginTimeoutError,
+            CredentialsNotFoundError,
+        ) as e:
+            # Clean up driver on login failure
             driver.quit()
-            return None
 
-        active_drivers[session_id] = driver
-        return driver
+            if config.chrome.non_interactive:
+                # In non-interactive mode, propagate the error
+                raise e
+            else:
+                # In interactive mode, handle the error
+                handle_login_error(e)
+                return None
     except Exception as e:
         error_msg = f"🛑 Error creating web driver: {e}"
         print(error_msg)
 
         if config.chrome.non_interactive:
-            print("🛑 Failed to initialize driver in non-interactive mode")
-            return None
+            raise DriverInitializationError(error_msg)
+        else:
+            raise WebDriverException(error_msg)
+
 
-        raise WebDriverException(error_msg)
+# Remove this function - linkedin-scraper now handles all error detection
 
 
 def login_to_linkedin(driver: webdriver.Chrome) -> bool:
@@ -116,59 +145,105 @@ def login_to_linkedin(driver: webdriver.Chrome) -> bool:
 
     Returns:
         bool: True if login was successful, False otherwise
+
+    Raises:
+        Various login-related errors from linkedin-scraper
     """
     config = get_config()
 
     # Get LinkedIn credentials from config
-    credentials = get_credentials()
+    try:
+        credentials = get_credentials()
+    except CredentialsNotFoundError as e:
+        if config.chrome.non_interactive:
+            raise e
+        # Only prompt if not in non-interactive mode
+        from linkedin_mcp_server.config.secrets import prompt_for_credentials
+
+        credentials = prompt_for_credentials()
 
     if not credentials:
-        print("❌ No credentials available")
-        return False
+        raise CredentialsNotFoundError("No credentials available")
 
-    try:
-        # Login to LinkedIn
-        print("🔑 Logging in to LinkedIn...")
+    # Login to LinkedIn using enhanced linkedin-scraper
+    print("🔑 Logging in to LinkedIn...")
 
-        from linkedin_scraper import actions  # type: ignore
+    from linkedin_scraper import actions  # type: ignore
 
-        actions.login(driver, credentials["email"], credentials["password"])
+    # linkedin-scraper now handles all error detection and raises appropriate exceptions
+    actions.login(
+        driver,
+        credentials["email"],
+        credentials["password"],
+        interactive=not config.chrome.non_interactive,
+    )
 
-        print("✅ Successfully logged in to LinkedIn")
-        return True
-    except Exception as e:
-        error_msg = f"Failed to login: {str(e)}"
-        print(f"❌ {error_msg}")
+    print("✅ Successfully logged in to LinkedIn")
+    return True
 
-        if not config.chrome.non_interactive:
+
+def handle_login_error(error: Exception) -> None:
+    """Handle login errors in interactive mode."""
+    config = get_config()
+
+    print(f"\n❌ Login failed: {str(error)}")
+
+    if isinstance(error, InvalidCredentialsError):
+        print("⚠️ Please check your email and password.")
+        retry = inquirer.prompt(
+            [
+                inquirer.Confirm(
+                    "retry",
+                    message="Would you like to try with different credentials?",
+                    default=True,
+                ),
+            ]
+        )
+        if retry and retry.get("retry", False):
+            # Clear credentials from keyring and try again
+            clear_credentials_from_keyring()
+            # Try again
+            initialize_driver()
+
+    elif isinstance(error, CaptchaRequiredError):
+        print("⚠️ LinkedIn requires captcha verification.")
+        captcha_url = getattr(error, "captcha_url", str(error))
+        print(f"🔗 Please complete the captcha at: {captcha_url}")
+        if config.chrome.headless:
             print(
-                "⚠️ You might need to confirm the login in your LinkedIn mobile app. "
-                "Please try again and confirm the login."
+                "🔍 Try running with visible browser window to complete captcha: "
+                "uv run main.py --no-headless"
             )
 
-            if config.chrome.headless:
-                print(
-                    "🔍 Try running with visible browser window to see what's happening: "
-                    "uv run main.py --no-headless"
-                )
+    elif isinstance(error, SecurityChallengeError):
+        print("⚠️ LinkedIn requires a security challenge.")
+        challenge_url = getattr(error, "challenge_url", str(error))
+        print(f"🔗 Please complete the security challenge at: {challenge_url}")
+        if config.chrome.headless:
+            print(
+                "🔍 Try running with visible browser window to complete challenge: "
+                "uv run main.py --no-headless"
+            )
 
-            retry = inquirer.prompt(
-                [
-                    inquirer.Confirm(
-                        "retry",
-                        message="Would you like to try with different credentials?",
-                        default=True,
-                    ),
-                ]
+    elif isinstance(error, TwoFactorAuthError):
+        print("⚠️ Two-factor authentication is required.")
+        print(
+            "📱 Please confirm the login in your LinkedIn mobile app or enter the 2FA code."
+        )
+        if config.chrome.headless:
+            print(
+                "🔍 Try running with visible browser window to complete 2FA: "
+                "uv run main.py --no-headless"
             )
 
-            if retry and retry.get("retry", False):
-                # Clear credentials from keyring and try again
-                clear_credentials_from_keyring()
-                # Try again with new credentials
-                return login_to_linkedin(driver)
+    elif isinstance(error, RateLimitError):
+        print("⚠️ Too many login attempts. Please wait before trying again.")
 
-        return False
+    elif isinstance(error, LoginTimeoutError):
+        print("⚠️ Login timed out. Please check your network connection.")
+
+    else:
+        print("⚠️ An unexpected error occurred during login.")
 
 
 def initialize_driver() -> None:
@@ -204,8 +279,30 @@ def initialize_driver() -> None:
         if driver:
             print("✅ Web driver initialized successfully")
         else:
+            if config.chrome.non_interactive:
+                raise DriverInitializationError(
+                    "Failed to initialize web driver in non-interactive mode"
+                )
             print("❌ Failed to initialize web driver.")
+    except (
+        CaptchaRequiredError,
+        InvalidCredentialsError,
+        SecurityChallengeError,
+        TwoFactorAuthError,
+        RateLimitError,
+        LoginTimeoutError,
+        CredentialsNotFoundError,
+    ) as e:
+        # In non-interactive mode, let the error propagate
+        if config.chrome.non_interactive:
+            raise e
+        # In interactive mode, handle gracefully
+        print(f"❌ Error: {str(e)}")
     except WebDriverException as e:
+        if config.chrome.non_interactive:
+            raise DriverInitializationError(
+                f"Failed to initialize web driver: {str(e)}"
+            )
         print(f"❌ Failed to initialize web driver: {str(e)}")
         handle_driver_error()
 
@@ -216,6 +313,11 @@ def handle_driver_error() -> None:
     """
     config = get_config()
 
+    # Skip interactive handling in non-interactive mode
+    if config.chrome.non_interactive:
+        print("❌ ChromeDriver is required for this application to work properly.")
+        sys.exit(1)
+
     questions = [
         inquirer.List(
             "chromedriver_action",