also proactively check native port

src/tui/managers/docling_manager.py

@@ -143,6 +143,29 @@ class DoclingManager:
         self._external_process = False
         return False
     
+    def check_port_available(self) -> tuple[bool, Optional[str]]:
+        """Check if the native service port is available.
+
+        Returns:
+            Tuple of (available, error_message)
+        """
+        import socket
+
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(0.5)
+            result = sock.connect_ex(('127.0.0.1', self._port))
+            sock.close()
+
+            if result == 0:
+                # Port is in use
+                return False, f"Port {self._port} is already in use"
+            return True, None
+        except Exception as e:
+            logger.debug(f"Error checking port {self._port}: {e}")
+            # If we can't check, assume it's available
+            return True, None
+
     def get_status(self) -> Dict[str, Any]:
         """Get current status of docling serve."""
         # Check for starting state first

src/tui/screens/monitor.py

@@ -415,6 +415,19 @@ class MonitorScreen(Screen):
         """Start docling serve."""
         self.operation_in_progress = True
         try:
+            # Check for port conflicts before attempting to start
+            port_available, error_msg = self.docling_manager.check_port_available()
+            if not port_available:
+                self.notify(
+                    f"Cannot start docling serve: {error_msg}. "
+                    f"Please stop the conflicting service first.",
+                    severity="error",
+                    timeout=10
+                )
+                # Refresh to show current state
+                await self._refresh_services()
+                return
+
             # Start the service (this sets _starting = True internally at the start)
             # Create task and let it begin executing (which sets the flag)
             start_task = asyncio.create_task(self.docling_manager.start())

src/tui/screens/welcome.py

@@ -385,6 +385,34 @@ class WelcomeScreen(Screen):
 
     async def _start_all_services(self) -> None:
         """Start all services: containers first, then native services."""
+        # Check for port conflicts before attempting to start anything
+        conflicts = []
+
+        # Check container ports
+        if self.container_manager.is_available():
+            ports_available, port_conflicts = await self.container_manager.check_ports_available()
+            if not ports_available:
+                for service_name, port, error_msg in port_conflicts[:3]:  # Show first 3
+                    conflicts.append(f"{service_name} (port {port})")
+                if len(port_conflicts) > 3:
+                    conflicts.append(f"and {len(port_conflicts) - 3} more")
+
+        # Check native service port
+        port_available, error_msg = self.docling_manager.check_port_available()
+        if not port_available:
+            conflicts.append(f"docling (port {self.docling_manager._port})")
+
+        # If there are any conflicts, show error and return
+        if conflicts:
+            conflict_str = ", ".join(conflicts)
+            self.notify(
+                f"Cannot start services: Port conflicts detected for {conflict_str}. "
+                f"Please stop the conflicting services first.",
+                severity="error",
+                timeout=10
+            )
+            return
+
         # Step 1: Start container services first (to create the network)
         if self.container_manager.is_available():
             command_generator = self.container_manager.start_services()
@@ -410,6 +438,20 @@ class WelcomeScreen(Screen):
     async def _start_native_services_after_containers(self) -> None:
         """Start native services after containers have been started."""
         if not self.docling_manager.is_running():
+            # Check for port conflicts before attempting to start
+            port_available, error_msg = self.docling_manager.check_port_available()
+            if not port_available:
+                self.notify(
+                    f"Cannot start native services: {error_msg}. "
+                    f"Please stop the conflicting service first.",
+                    severity="error",
+                    timeout=10
+                )
+                # Update state and return
+                self.docling_running = False
+                await self._refresh_welcome_content()
+                return
+
             self.notify("Starting native services...", severity="information")
             success, message = await self.docling_manager.start()
             if success: