Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

improvement: better lsp logging (#7085)

Myles Scolnicke02859e1c6d2
diff --git a/marimo/_server/lsp.py b/marimo/_server/lsp.py
index 03863aff6f..d272441c82 100644
--- a/marimo/_server/lsp.py
+++ b/marimo/_server/lsp.py
@@ -16,6 +16,7 @@ from marimo._messaging.ops import Alert
from marimo._server.utils import find_free_port
from marimo._tracer import server_tracer
from marimo._utils.paths import marimo_package_path
+from marimo._utils.platform import is_windows
LOGGER = _loggers.marimo_logger()
@@ -41,6 +42,9 @@ class BaseLspServer(LspServer):
def __init__(self, port: int) -> None:
self.port = port
self.process: Optional[subprocess.Popen[str]] = None
+ self._health_check_task: Optional[asyncio.Task[None]] = None
+ self._startup_failed = False
+ self.log_file = _loggers.get_log_directory() / f"{self.id}.log"
@server_tracer.start_as_current_span("lsp_server.start")
async def start(self) -> Optional[Alert]:
@@ -72,8 +76,9 @@ class BaseLspServer(LspServer):
stdout=subprocess.PIPE
if GLOBAL_SETTINGS.DEVELOPMENT_MODE
else subprocess.DEVNULL,
- # subprocess.PIPE in Windows breaks the lsp-server
- stderr=subprocess.DEVNULL,
+ # Capture stderr to diagnose startup failures
+ # but subprocess.PIPE in Windows breaks the lsp-server
+ stderr=subprocess.DEVNULL if is_windows() else subprocess.PIPE,
stdin=None,
text=True,
)
@@ -87,25 +92,35 @@ class BaseLspServer(LspServer):
self.process.returncode is not None
and self.process.returncode != 0
):
- # Process failed immediately
+ # Process failed immediately - read stderr to diagnose
stderr_output = (
self.process.stderr.read()
if self.process.stderr
else "No error output available"
)
LOGGER.error(
- "LSP server failed to start with return code %s",
- self.process.returncode,
+ f"{self.id} LSP server failed to start with return code {self.process.returncode}"
)
- LOGGER.error("Error output: %s", stderr_output)
+ LOGGER.error(f"Command: {' '.join(cmd)}")
+ LOGGER.error(f"Error output: {stderr_output}")
+
return Alert(
- title="LSP server failed to start",
- description="The LSP server failed to start. Please check the logs for more information.",
+ title=f"{self.id} LSP server failed to start",
+ description=f"The {self.id} server crashed on startup. Check {self.log_file} for details. Error: {stderr_output[:200]}",
variant="danger",
)
LOGGER.info(f"Started LSP {self.id} at port {self.port}")
+ # Start health monitoring in background
+ if (
+ self._health_check_task is None
+ or self._health_check_task.done()
+ ):
+ self._health_check_task = asyncio.create_task(
+ self._monitor_process_health()
+ )
+
except Exception as e:
cmd_str = " ".join(cmd or [])
LOGGER.error(
@@ -120,9 +135,64 @@ class BaseLspServer(LspServer):
return False
# check if the process is still running
self.process.poll()
- return self.process.returncode is not None
+ # returncode is None when process is running, set when it exits
+ return self.process.returncode is None
+
+ def has_failed(self) -> bool:
+ """Check if the LSP server has failed to start or crashed."""
+ return self._startup_failed or (
+ self.process is not None
+ and self.process.returncode is not None
+ and self.process.returncode != 0
+ )
+
+ async def _monitor_process_health(self) -> None:
+ """Monitor the LSP process health and log if it crashes."""
+ if self.process is None:
+ return
+
+ try:
+ # Wait a bit to let the process fully initialize
+ await asyncio.sleep(2)
+
+ # Wait for the process to exit (non-blocking via executor)
+ loop = asyncio.get_running_loop()
+ await loop.run_in_executor(None, self.process.wait)
+
+ # Process has exited - check if it was expected
+ if self.process and self.process.returncode is not None:
+ stderr_output = ""
+ if self.process.stderr:
+ try:
+ # Try to read any remaining stderr
+ # Note: stderr might be empty if already consumed during wait()
+ stderr_output = self.process.stderr.read()
+ except Exception:
+ pass
+
+ LOGGER.error(
+ f"{self.id} LSP server crashed unexpectedly with exit code {self.process.returncode}. Check {self.log_file} for details."
+ )
+ if stderr_output:
+ LOGGER.error(f"stderr: {stderr_output}")
+
+ self._startup_failed = True
+
+ except asyncio.CancelledError:
+ # Task was cancelled, this is normal during shutdown
+ # Re-raise to properly complete the cancellation
+ raise
+ except Exception as e:
+ LOGGER.error(f"Error monitoring {self.id} LSP health: {e}")
def stop(self) -> None:
+ # Cancel health monitoring task
+ if (
+ self._health_check_task is not None
+ and not self._health_check_task.done()
+ ):
+ self._health_check_task.cancel()
+
if self.process is not None:
self.process.terminate()
self.process = None
@@ -143,6 +213,10 @@ class BaseLspServer(LspServer):
class CopilotLspServer(BaseLspServer):
id = "copilot"
+ def __init__(self, port: int) -> None:
+ super().__init__(port)
+ self.log_file = _loggers.get_log_directory() / "github-copilot-lsp.log"
+
def validate_requirements(self) -> Union[str, Literal[True]]:
if not DependencyManager.which("node"):
return "node.js binary is missing. Install node at https://nodejs.org/."
@@ -197,7 +271,6 @@ class CopilotLspServer(BaseLspServer):
return []
copilot_bin = self._lsp_dir() / "copilot" / "language-server.cjs"
- log_file = _loggers.get_log_directory() / "github-copilot-lsp.log"
# Use typed format to avoid quoting issues: copilot:<binary_path>
copilot_command = f"copilot:{copilot_bin}"
@@ -210,7 +283,7 @@ class CopilotLspServer(BaseLspServer):
"--lsp",
copilot_command,
"--log-file",
- str(log_file),
+ str(self.log_file),
]
def missing_binary_alert(self) -> Alert:
@@ -222,25 +295,52 @@ class CopilotLspServer(BaseLspServer):
class PyLspServer(BaseLspServer):
+ """Python Language Server Protocol implementation using python-lsp-server (pylsp).
+
+ Common issues and solutions:
+ - If pylsp fails to start, check ~/.cache/marimo/logs/pylsp.log for errors
+ - Version conflicts between jedi and python-lsp-server can cause failures
+ - If autocomplete doesn't work, try disabling pylsp in Settings > Editor > Language Servers
+ - When pylsp is disabled, marimo falls back to Jedi for completions
+ """
+
id = "pylsp"
async def start(self) -> Optional[Alert]:
# pylsp is not required, so we don't want to alert or fail if it is not installed
if not DependencyManager.pylsp.has():
- LOGGER.debug("pylsp is not installed. Skipping LSP server.")
+ LOGGER.info(
+ "pylsp is not installed. Skipping LSP server. Install with: pip install python-lsp-server"
+ )
return None
return await super().start()
def validate_requirements(self) -> Union[str, Literal[True]]:
- if DependencyManager.pylsp.has():
+ if not DependencyManager.pylsp.has():
+ return "pylsp is missing. Install it with `pip install python-lsp-server`."
+
+ # Try actually running pylsp to validate it works
+ import sys
+
+ try:
+ result = subprocess.run(
+ [sys.executable, "-m", "pylsp", "--version"],
+ capture_output=True,
+ text=True,
+ timeout=5,
+ )
+ if result.returncode != 0:
+ error_msg = result.stderr or result.stdout or "Unknown error"
+ return f"pylsp is installed but failed to run: {error_msg}. Check for dependency conflicts (e.g., jedi version compatibility)."
return True
- return "pylsp is missing. Install it with `pip install python-lsp-server`."
+ except subprocess.TimeoutExpired:
+ return "pylsp command timed out. The server may be unresponsive."
+ except Exception as e:
+ return f"Failed to validate pylsp: {e}"
def get_command(self) -> list[str]:
import sys
- log_file = _loggers.get_log_directory() / "pylsp.log"
-
return [
sys.executable,
"-m",
@@ -251,13 +351,13 @@ class PyLspServer(BaseLspServer):
str(self.port),
"--check-parent-process",
"--log-file",
- str(log_file),
+ str(self.log_file),
]
def missing_binary_alert(self) -> Alert:
return Alert(
title="Python LSP: Connection Error",
- description="<span><a class='hyperlink' href='https://github.com/python-lsp/python-lsp-server'>Install python-lsp-server</a> for Python language support.</span>",
+ description=f"<span><a class='hyperlink' href='https://github.com/python-lsp/python-lsp-server'>Install python-lsp-server</a> for Python language support. If already installed, check {self.log_file} or disable pylsp in Settings > Editor > Language Servers.</span>",
variant="danger",
)
@@ -265,6 +365,10 @@ class PyLspServer(BaseLspServer):
class BasedpyrightServer(BaseLspServer):
id = "basedpyright"
+ def __init__(self, port: int) -> None:
+ super().__init__(port)
+ self.log_file = _loggers.get_log_directory() / "basedpyright-lsp.log"
+
async def start(self) -> Optional[Alert]:
# basedpyright is not required, so we don't want to alert or fail if it is not installed
if not DependencyManager.basedpyright.has():
@@ -283,7 +387,6 @@ class BasedpyrightServer(BaseLspServer):
def get_command(self) -> list[str]:
lsp_bin = marimo_package_path() / "_lsp" / "index.cjs"
- log_file = _loggers.get_log_directory() / "basedpyright-lsp.log"
return [
"node",
@@ -293,7 +396,7 @@ class BasedpyrightServer(BaseLspServer):
"--lsp",
"basedpyright:basedpyright-langserver",
"--log-file",
- str(log_file),
+ str(self.log_file),
]
def missing_binary_alert(self) -> Alert:
@@ -307,6 +410,10 @@ class BasedpyrightServer(BaseLspServer):
class TyServer(BaseLspServer):
id = "ty"
+ def __init__(self, port: int) -> None:
+ super().__init__(port)
+ self.log_file = _loggers.get_log_directory() / "ty-lsp.log"
+
async def start(self) -> Optional[Alert]:
# ty is not required, so we don't want to alert or fail if it is not installed
if not DependencyManager.ty.has():
@@ -327,7 +434,6 @@ class TyServer(BaseLspServer):
from ty.__main__ import find_ty_bin # type: ignore
lsp_bin = marimo_package_path() / "_lsp" / "index.cjs"
- log_file = _loggers.get_log_directory() / "ty-lsp.log"
# Use typed format to avoid quoting issues: ty:<binary_path>
ty_command = f"ty:{find_ty_bin()}"
@@ -340,7 +446,7 @@ class TyServer(BaseLspServer):
"--lsp",
ty_command,
"--log-file",
- str(log_file),
+ str(self.log_file),
]
def missing_binary_alert(self) -> Alert:
diff --git a/marimo/_server/sessions.py b/marimo/_server/sessions.py
index 3538122f68..4335d1173a 100644
--- a/marimo/_server/sessions.py
+++ b/marimo/_server/sessions.py
@@ -1073,18 +1073,18 @@ class SessionManager:
LOGGER.warning("Cannot start LSP server in run mode")
return
- LOGGER.debug("Starting LSP server...")
+ LOGGER.info("Starting LSP server...")
alert = await self.lsp_server.start()
if alert is not None:
- LOGGER.warning(
+ LOGGER.error(
f"LSP server startup failed: {alert.title} - {alert.description}"
)
for session in self.sessions.values():
session.write_operation(alert, from_consumer_id=None)
return
else:
- LOGGER.debug("LSP server started successfully")
+ LOGGER.info("LSP server started successfully")
def close_session(self, session_id: SessionId) -> bool:
"""Close a session and remove its file watcher if it has one."""
diff --git a/tests/_server/test_lsp.py b/tests/_server/test_lsp.py
index 3a4acadb56..4863558c1b 100644
--- a/tests/_server/test_lsp.py
+++ b/tests/_server/test_lsp.py
@@ -83,7 +83,9 @@ async def test_base_lsp_server_start_stop(
alert = await server.start()
assert alert is None
mock_popen.assert_called_once()
- assert server.is_running() is False # Process exists but not running
+ assert (
+ server.is_running() is True
+ ) # Process exists and is running (returncode is None)
# Test stop
server.stop()