fix: add troubleshooting docs and more logging (#66)

* fix: add troubleshooting docs and more logging

* update logs

README.md

@@ -41,6 +41,47 @@ This feature is experimental and may have some limitations. Some known limitatio
 - For autocomplete to work when using native VSCode notebooks for many packages (including `marimo`, `numpy`, and more) you may be required to include a `pyproject.toml` file at the root of the workspace. marimo's editor gets around this by default but unfortunately, the VSCode's native notebook does not.
 - You cannot access **many** marimo features in the native notebook (and need to use the marimo browser), such as the variable explorer, dependency viewer, grid mode (plus other layouts), and more - so we show the notebook in "Kiosk Mode" which is a read-only view of the outputs and helper panels.
 
+## Python Configuration
+
+To ensure marimo works correctly with your Python environment, you have several options:
+
+1. **Workspace Settings (Recommended)**
+   Create or edit `.vscode/settings.json` in your workspace:
+
+   ```json
+   {
+     "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+     "marimo.marimoPath": "${workspaceFolder}/.venv/bin/marimo"
+   }
+   ```
+
+2. **Global Settings**
+   You can also configure these settings globally in VS Code's settings:
+
+   - Set `python.defaultInterpreterPath` to your preferred Python interpreter
+   - (Likely not needed) Set `marimo.marimoPath` to the path of your marimo installation
+   - Verify that marimo is available in your Python interpreter: `value/of/defaultInterpreterPath -m marimo`
+
+3. **Virtual Environments**
+   If using a virtual environment:
+   - Create and activate your virtual environment
+   - Install marimo: `pip install marimo`
+   - VS Code should automatically detect the Python interpreter
+
+4. **uv and package environment sandboxes**
+   You can use `uvx` with `marimo edit --sandbox` to run marimo in a sandbox.
+
+   ```json
+   {
+     "marimo.pythonPath": "uv run python",
+     "marimo.marimoPath": "marimo",
+     "marimo.sandbox": true
+   }
+   ```
+
+> [!TIP]
+> The extension will use the Python interpreter from the Python extension by default. Make sure you have the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) installed and configured.
+
 ## Extension Settings
 
 You can configure the extension using the following settings:
@@ -56,3 +97,9 @@ You can configure the extension using the following settings:
 - `marimo.debug`: Enable debug logging (default: `false`)
 - `marimo.pythonPath`: Path to python interpreter (default: the one from python extension)
 - `marimo.marimoPath`: Path to marimo executable (default: `marimo`)
+
+## Troubleshooting
+
+If you encounter issues, you can open the marimo extension logs by running the `marimo: Show marimo status` command from the command palette.
+
+You can also hover over the marimo status bar item in the bottom left of the VSCode window to see the status of the marimo extension.

package.json

@@ -359,7 +359,7 @@
         "marimo.pythonPath": {
           "type": "string",
           "default": null,
-          "description": "The path to the Python interpreter to use. If not set, the default Python interpreter will be used."
+          "description": "The path to the Python interpreter to use. If not set, the active Python interpreter will be used, then the default interpreter (python.defaultInterpreterPath) will be used."
         },
         "marimo.marimoPath": {
           "type": "string",

src/commands/show-commands.ts

@@ -216,7 +216,7 @@ export function miscCommands(serverManager: ServerManager): CommandPickItem[] {
       handler: async () => {
         // Open output panel with channel 'marimo'
         await commands.executeCommand(
-          `workbench.action.output.show.extension-output-${EXTENSION_PACKAGE.fullName}-#1-${EXTENSION_DISPLAY_NAME}`,
+          `workbench.action.output.show.${EXTENSION_PACKAGE.fullName}.${EXTENSION_DISPLAY_NAME}`,
         );
         await commands.executeCommand(
           "marimo-explorer-running-applications.focus",

src/extension.ts

@@ -128,8 +128,12 @@ class MarimoExtension {
         cancellable: false,
       },
       async () => {
-        const response = await this.serverManager.start();
-        await this.kernelManager.hydrateExistingNotebooks(response);
+        try {
+          const response = await this.serverManager.start();
+          await this.kernelManager.hydrateExistingNotebooks(response);
+        } catch (e) {
+          window.showErrorMessage(`Failed to start marimo server: ${e}`);
+        }
       },
     );
   }

src/launcher/controller.ts

@@ -102,6 +102,7 @@ export class MarimoController implements Disposable {
 
     const interpreter = await getInterpreter();
     if (interpreter) {
+      logger.info(`Using interpreter ${interpreter}`);
       await this.terminal.executeCommand(`${interpreter} -m ${cmd}`);
     } else {
       await this.terminal.executeCommand(cmd);

src/launcher/utils.ts

@@ -1,5 +1,6 @@
 import { parse } from "node-html-parser";
 import { composeUrl } from "../config";
+import { logger } from "../logger";
 import type { MarimoConfig, SkewToken } from "../notebook/marimo/types";
 import { asURL } from "../utils/url";
 
@@ -16,7 +17,13 @@ export async function fetchMarimoStartupValues(port: number): Promise<{
   userConfig: MarimoConfig;
 }> {
   const url = asURL(await composeUrl(port));
-  const response = await fetch(url.toString());
+  let response: Response;
+  try {
+    response = await fetch(url.toString());
+  } catch (e) {
+    logger.error(`Could not fetch ${url}. Is ${url} healthy?`);
+    throw new Error(`Could not fetch ${url}. Is ${url} healthy?`);
+  }
 
   if (!response.ok) {
     throw new Error(

src/services/health.ts

@@ -46,11 +46,44 @@ export class HealthService {
    * Shows an alert with the status of the server
    */
   public async showStatus() {
-    await window.showInformationMessage(await this.printStatus(), {
+    await window.showInformationMessage(await this.printStatusVerbose(), {
       modal: true,
     });
   }
 
+  public async printStatusVerbose(): Promise<string> {
+    const [{ isInstalled, version, path }, pythonInterpreter] =
+      await Promise.all([this.isMarimoInstalled(), getInterpreter()]);
+
+    if (isInstalled) {
+      const status = await this.isServerRunning();
+      return [
+        "marimo configuration:",
+        `\tpython interpreter: ${pythonInterpreter}`,
+        path === "marimo" ? "" : `\tmarimo executable path: ${path}`, // don't show if default
+        `\tversion: ${version}`,
+        "",
+        "server status:",
+        status.isRunning ? `\trunning on port ${status.port}` : "\tnot running",
+        "",
+        "configuration:",
+        `\thost: ${Config.host}`,
+        `\tdefault port: ${Config.port}`,
+        `\tread port: ${Config.readPort}`,
+        `\thttps enabled: ${Config.https}`,
+        `\ttoken auth enabled: ${Config.enableToken}`,
+        `\tsandbox mode: ${Config.sandbox}`,
+        `\tbrowser type: ${Config.browser}`,
+        `\tshow terminal: ${Config.showTerminal}`,
+        `\tdebug mode: ${Config.debug}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    }
+
+    return troubleShootingMessage(path, pythonInterpreter);
+  }
+
   public async printStatus(): Promise<string> {
     const [{ isInstalled, version, path }, pythonInterpreter] =
       await Promise.all([this.isMarimoInstalled(), getInterpreter()]);
@@ -59,7 +92,7 @@ export class HealthService {
       const status = await this.isServerRunning();
       return [
         "marimo is installed",
-        path === "marimo" ? "" : `\tmarimo executable path: ${path}`,
+        path === "marimo" ? "" : `\tmarimo executable path: ${path}`, // don't show if default
         `\tpython interpreter: ${pythonInterpreter}`,
         `\tversion: ${version}`,
         status.isRunning
@@ -70,6 +103,26 @@ export class HealthService {
         .join("\n");
     }
 
-    return `marimo does not appear to be installed at: ${path}`;
+    return troubleShootingMessage(path, pythonInterpreter);
   }
 }
+
+function troubleShootingMessage(
+  marimoPath: string,
+  pythonInterpreter: string | undefined,
+) {
+  return [
+    "marimo does not appear to be installed.",
+    "",
+    "Current configuration:",
+    `\tpython interpreter: ${pythonInterpreter || "not set"}`,
+    marimoPath === "marimo" ? "" : `\tmarimo executable path: ${marimoPath}`, // don't show if default
+    "",
+    "Troubleshooting steps:",
+    `\t1. Verify installation: ${pythonInterpreter} -m ${marimoPath}`,
+    "\t2. Install marimo: pip install marimo",
+    "\t3. Check python.defaultInterpreterPath in VS Code settings",
+    "\t4. Try creating a new virtual environment",
+    "\t5. If using a virtual environment, ensure it's activated",
+  ].join("\n");
+}

src/services/server-manager.ts

@@ -289,6 +289,7 @@ export class ServerManager implements IServerManager {
   private async executeServerCommand(cmd: string): Promise<void> {
     const interpreter = await getInterpreter();
     if (interpreter) {
+      logger.info(`Using interpreter ${interpreter}`);
       await this.terminal.executeCommand(`${interpreter} -m ${cmd}`);
     } else {
       await this.terminal.executeCommand(cmd);