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.

fix: pretty format hidden variable behavior in stack traces (#9660)

Dylan Madisettiddf04cd40024
diff --git a/frontend/src/components/editor/errors/mangled-local-chip.tsx b/frontend/src/components/editor/errors/mangled-local-chip.tsx
new file mode 100644
index 0000000000..bbf60bb273
--- /dev/null
+++ b/frontend/src/components/editor/errors/mangled-local-chip.tsx
@@ -0,0 +1,50 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { JSX } from "react";
+import { Tooltip } from "@/components/ui/tooltip";
+import type { MangledSegment, UnmangledLocal } from "@/utils/local-variables";
+import { CellLinkError } from "../links/cell-link";
+
+interface Props {
+ local: UnmangledLocal;
+}
+
+/**
+ * Renders a compiler-mangled cell-local variable as the user's original name
+ * (e.g. `_a`) with a tooltip linking to the defining cell.
+ */
+export const MangledLocalChip = ({ local }: Props): JSX.Element => {
+ const tooltipContent = (
+ <div className="max-w-xs">
+ Local variable <span className="font-code">{local.name}</span> in cell{" "}
+ <CellLinkError cellId={local.cellId} />.
+ </div>
+ );
+
+ return (
+ <Tooltip content={tooltipContent}>
+ <span className="font-code cursor-help">{local.name}</span>
+ </Tooltip>
+ );
+};
+
+interface MangledSegmentsProps {
+ segments: MangledSegment[];
+}
+
+/**
+ * Render an array of `splitMangledLocals` segments as alternating text and
+ * `<MangledLocalChip>` nodes.
+ */
+export const MangledSegments = ({
+ segments,
+}: MangledSegmentsProps): JSX.Element => (
+ <>
+ {segments.map((segment, idx) =>
+ typeof segment === "string" ? (
+ <span key={idx}>{segment}</span>
+ ) : (
+ <MangledLocalChip key={idx} local={segment} />
+ ),
+ )}
+ </>
+);
diff --git a/frontend/src/components/editor/output/MarimoErrorOutput.tsx b/frontend/src/components/editor/output/MarimoErrorOutput.tsx
index db5d8e9741..1d9c1f32e6 100644
--- a/frontend/src/components/editor/output/MarimoErrorOutput.tsx
+++ b/frontend/src/components/editor/output/MarimoErrorOutput.tsx
@@ -17,15 +17,17 @@ import { Button } from "@/components/ui/button";
import { Kbd } from "@/components/ui/kbd";
import { ExternalLink } from "@/components/ui/links";
import type { CellId } from "@/core/cells/ids";
+import { renderHTML } from "@/plugins/core/RenderHTML";
+import { splitMangledLocals } from "@/utils/local-variables";
import type { MarimoError } from "../../../core/kernel/messages";
import { cn } from "../../../utils/cn";
import { Alert, AlertTitle } from "../../ui/alert";
import { openPackageManager } from "../chrome/panels/packages-utils";
import { useChromeActions } from "../chrome/state";
import { AutoFixButton } from "../errors/auto-fix";
+import { MangledSegments } from "../errors/mangled-local-chip";
import { CellLinkError } from "../links/cell-link";
import { processTextForUrls } from "./console/text-rendering";
-import { renderHTML } from "@/plugins/core/RenderHTML";
const Tip = (props: {
title?: string;
@@ -454,10 +456,13 @@ export const MarimoErrorOutput = ({
error.exception_type === "NameError" &&
error.msg.startsWith("name '_")
) {
+ const segments = splitMangledLocals(error.msg);
return (
<li className="my-2" key={`exception-${idx}`}>
<div>
- <p className="text-muted-foreground">{error.msg}</p>
+ <p className="text-muted-foreground">
+ <MangledSegments segments={segments} />
+ </p>
<p className="text-muted-foreground mt-2">
Variables prefixed with an underscore are local to a cell{" "}
(
diff --git a/frontend/src/components/editor/output/MarimoTracebackOutput.tsx b/frontend/src/components/editor/output/MarimoTracebackOutput.tsx
index d541932aef..1f447c73ba 100644
--- a/frontend/src/components/editor/output/MarimoTracebackOutput.tsx
+++ b/frontend/src/components/editor/output/MarimoTracebackOutput.tsx
@@ -36,6 +36,10 @@ import { isWasm } from "@/core/wasm/utils";
import { renderHTML } from "@/plugins/core/RenderHTML";
import { sanitizeHtml } from "@/plugins/core/sanitize-html";
import { copyToClipboard } from "@/utils/copy";
+import {
+ containsMangledLocal,
+ splitMangledLocals,
+} from "@/utils/local-variables";
import {
elementContainsMarimoCellFile,
extractAllTracebackInfo,
@@ -43,6 +47,7 @@ import {
} from "@/utils/traceback";
import { cn } from "../../../utils/cn";
import { AIFixButton } from "../errors/auto-fix";
+import { MangledSegments } from "../errors/mangled-local-chip";
import { CellLinkTraceback } from "../links/cell-link";
import type { OnRefactorWithAI } from "../Output";
@@ -64,7 +69,11 @@ export const MarimoTracebackOutput = ({
}: Props): JSX.Element => {
const htmlTraceback = renderHTML({
html: traceback,
- additionalReplacements: [replaceTracebackFilenames, replaceTracebackPrefix],
+ additionalReplacements: [
+ replaceTracebackFilenames,
+ replaceTracebackPrefix,
+ replaceMangledLocal,
+ ],
});
const [expanded, setExpanded] = useState(true);
@@ -94,6 +103,9 @@ export const MarimoTracebackOutput = ({
};
const [error, errorMessage] = lastTracebackLine.split(":", 2);
+ const errorMessageSegments = errorMessage
+ ? splitMangledLocals(errorMessage)
+ : [];
return (
<div className="flex flex-col gap-2 min-w-full w-fit">
@@ -111,7 +123,7 @@ export const MarimoTracebackOutput = ({
/>
<div className="text-sm inline font-mono">
<span className="text-destructive">{error || "Error"}:</span>{" "}
- {errorMessage}
+ <MangledSegments segments={errorMessageSegments} />
</div>
</div>
<AccordionContent className="text-muted-foreground px-4 pt-2 text-xs overflow-auto">
@@ -249,6 +261,23 @@ export const replaceTracebackFilenames = (domNode: DOMNode) => {
}
};
+/**
+ * Replace any cell-local mangled name (`_cell_<id>_<name>`) inside a text
+ * node with a {@link MangledLocalChip}. The mangled name appears in both
+ * the final `NameError:` line and inside compiled-cell source lines because
+ * the compiler rewrites underscore-prefixed references at AST-visit time.
+ */
+export const replaceMangledLocal = (domNode: DOMNode) => {
+ if (!(domNode instanceof Text) || !domNode.nodeValue) {
+ return;
+ }
+ if (!containsMangledLocal(domNode.nodeValue)) {
+ return;
+ }
+ const segments = splitMangledLocals(domNode.nodeValue);
+ return <MangledSegments segments={segments} />;
+};
+
export const replaceTracebackPrefix = (domNode: DOMNode) => {
if (
domNode instanceof Text &&
diff --git a/frontend/src/utils/__tests__/local-variables.test.ts b/frontend/src/utils/__tests__/local-variables.test.ts
new file mode 100644
index 0000000000..fcf61f67f0
--- /dev/null
+++ b/frontend/src/utils/__tests__/local-variables.test.ts
@@ -0,0 +1,132 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import {
+ containsMangledLocal,
+ splitMangledLocals,
+ unmangleLocal,
+} from "../local-variables";
+
+describe("unmangleLocal", () => {
+ it("extracts the cell id and original name", () => {
+ expect(unmangleLocal("_cell_Hbol_a")).toEqual({
+ cellId: "Hbol",
+ name: "_a",
+ });
+ });
+
+ it("handles names with multiple underscore segments", () => {
+ expect(unmangleLocal("_cell_Hbol_a_b")).toEqual({
+ cellId: "Hbol",
+ name: "_a_b",
+ });
+ });
+
+ it("returns null for non-mangled strings", () => {
+ expect(unmangleLocal("just_a_variable")).toBeNull();
+ expect(unmangleLocal("_private")).toBeNull();
+ });
+
+ it("handles the single-underscore local", () => {
+ // `_` is a valid local name (variables.py:62-63), mangling to
+ // `_cell_<id>_` with no trailing suffix.
+ expect(unmangleLocal("_cell_Hbol_")).toEqual({
+ cellId: "Hbol",
+ name: "_",
+ });
+ });
+
+ it("handles UUID-style cell ids", () => {
+ // External / VSCode notebooks use `external_prefix()` which is a
+ // `uuid4()` (hyphenated).
+ expect(
+ unmangleLocal("_cell_c9bf9e57-1685-4c89-bafb-ff5af830be8a_a"),
+ ).toEqual({
+ cellId: "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
+ name: "_a",
+ });
+ });
+
+ it("does not match marimo cell file paths", () => {
+ // The compiled cell file is `__marimo__cell_<id>_.py` (two leading
+ // underscores, trailing `_` with no name); it must not be confused with a
+ // mangled local.
+ expect(unmangleLocal("__marimo__cell_Hbol_.py")).toBeNull();
+ expect(unmangleLocal("/tmp/marimo_42/__marimo__cell_Hbol_.py")).toBeNull();
+ });
+});
+
+describe("splitMangledLocals", () => {
+ it("returns a single text segment when nothing matches", () => {
+ expect(splitMangledLocals("plain text")).toEqual(["plain text"]);
+ });
+
+ it("splits a NameError message", () => {
+ expect(splitMangledLocals("name '_cell_Hbol_a' is not defined")).toEqual([
+ "name '",
+ { cellId: "Hbol", name: "_a" },
+ "' is not defined",
+ ]);
+ });
+
+ it("handles multiple mangled names in one string", () => {
+ expect(splitMangledLocals("_cell_AAAA_x and _cell_BBBB_y")).toEqual([
+ { cellId: "AAAA", name: "_x" },
+ " and ",
+ { cellId: "BBBB", name: "_y" },
+ ]);
+ });
+
+ it("leaves the cell file path alone", () => {
+ const path = "/tmp/marimo_42/__marimo__cell_Hbol_.py";
+ expect(splitMangledLocals(path)).toEqual([path]);
+ });
+
+ it("ignores `_cell_...` substrings preceded by `_`", () => {
+ // Mirrors `(?<!_)` in `variables.py`: a leading `_` (e.g. inside
+ // `__marimo__cell_<id>_<...>`) means this is not a mangle the compiler
+ // produced, so we must not demangle it.
+ const text = "see __marimo__cell_Hbol_a for details";
+ expect(splitMangledLocals(text)).toEqual([text]);
+ });
+
+ it("splits a UUID-style cell id", () => {
+ expect(
+ splitMangledLocals(
+ "name '_cell_c9bf9e57-1685-4c89-bafb-ff5af830be8a_a' is not defined",
+ ),
+ ).toEqual([
+ "name '",
+ {
+ cellId: "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
+ name: "_a",
+ },
+ "' is not defined",
+ ]);
+ });
+
+ it("splits the single-underscore local", () => {
+ expect(splitMangledLocals("name '_cell_Hbol_' is not defined")).toEqual([
+ "name '",
+ { cellId: "Hbol", name: "_" },
+ "' is not defined",
+ ]);
+ });
+});
+
+describe("containsMangledLocal", () => {
+ it("detects mangled names", () => {
+ expect(containsMangledLocal("name '_cell_Hbol_a' is not defined")).toBe(
+ true,
+ );
+ });
+
+ it("ignores the cell file path", () => {
+ expect(containsMangledLocal("/tmp/marimo_42/__marimo__cell_Hbol_.py")).toBe(
+ false,
+ );
+ });
+
+ it("ignores `_cell_...` substrings preceded by `_`", () => {
+ expect(containsMangledLocal("see __marimo__cell_Hbol_a")).toBe(false);
+ });
+});
diff --git a/frontend/src/utils/local-variables.ts b/frontend/src/utils/local-variables.ts
new file mode 100644
index 0000000000..e52a48f72f
--- /dev/null
+++ b/frontend/src/utils/local-variables.ts
@@ -0,0 +1,67 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { CellId } from "@/core/cells/ids";
+
+/**
+ * The marimo compiler rewrites underscore-prefixed references inside a cell
+ * (which Python would treat as module-private) into `_cell_<cell_id>_<name>`
+ * so each cell gets its own private namespace. When such a reference fails at
+ * runtime (`NameError: name '_cell_Hbol_a' is not defined`), the mangled name
+ * leaks into the error UI. These helpers undo that mangling for display.
+ *
+ * Mirrors `marimo/_ast/variables.py`.
+ */
+
+// Matches `_cell_<cell_id><name>` for normal ids and UUIDs. The `[\w-]`
+// id class admits hyphens; the `_\w*` name group admits the bare `_`
+// local; the `(?<!_)` lookbehind skips `__marimo__cell_...` paths.
+// Mirrors `_MANGLED_LOCAL_IN_TEXT_RE` in `variables.py`.
+const MANGLED_LOCAL_BODY = String.raw`_cell_([^\W_][\w-]*?)(_\w*)`;
+const MANGLED_LOCAL_PATTERN = String.raw`(?<!_)${MANGLED_LOCAL_BODY}`;
+// Strict (whole-string) form for `unmangleLocal`; the leading `^` makes the
+// lookbehind trivially satisfied, so use the bare body.
+const ANCHORED_RE = new RegExp(`^${MANGLED_LOCAL_BODY}$`);
+const UNANCHORED_RE = new RegExp(MANGLED_LOCAL_PATTERN);
+const GLOBAL_RE = new RegExp(MANGLED_LOCAL_PATTERN, "g");
+
+export interface UnmangledLocal {
+ cellId: CellId;
+ /** The original underscore-prefixed name, e.g. "_a". */
+ name: string;
+}
+
+export function unmangleLocal(mangled: string): UnmangledLocal | null {
+ const match = ANCHORED_RE.exec(mangled);
+ if (!match) {
+ return null;
+ }
+ return { cellId: match[1] as CellId, name: match[2] };
+}
+
+export type MangledSegment = string | UnmangledLocal;
+
+/**
+ * Split a plain text string into alternating literal text and unmangled-local
+ * segments, so callers can render mixed React content.
+ */
+export function splitMangledLocals(text: string): MangledSegment[] {
+ const segments: MangledSegment[] = [];
+ GLOBAL_RE.lastIndex = 0;
+ let lastIndex = 0;
+ let match: RegExpExecArray | null = GLOBAL_RE.exec(text);
+ while (match !== null) {
+ if (match.index > lastIndex) {
+ segments.push(text.slice(lastIndex, match.index));
+ }
+ segments.push({ cellId: match[1] as CellId, name: match[2] });
+ lastIndex = match.index + match[0].length;
+ match = GLOBAL_RE.exec(text);
+ }
+ if (lastIndex < text.length) {
+ segments.push(text.slice(lastIndex));
+ }
+ return segments;
+}
+
+export function containsMangledLocal(text: string): boolean {
+ return UNANCHORED_RE.test(text);
+}
diff --git a/marimo/_ast/variables.py b/marimo/_ast/variables.py
index f0554ab7da..28d04b24c2 100644
--- a/marimo/_ast/variables.py
+++ b/marimo/_ast/variables.py
@@ -68,3 +68,14 @@ def get_cell_from_local(
) -> CellId_t | None:
local = unmangle_local(if_local_then_mangle(name, cell_id)).cell
return local if local else None
+
+
+# Demangle every occurrence of `_cell_<cell_id><_name>` inside a free-form
+# string (test output, traceback lines, etc.) back to `<_name>`. Matches
+# normal ids and UUIDs; the `(?<!_)` lookbehind skips the compiled cell-file
+# path `__marimo__cell_<id>_.py`, which carries a leading `_`.
+_MANGLED_LOCAL_IN_TEXT_RE = re.compile(r"(?<!_)_cell_(?:[^\W_][\w-]*?)(_\w*)")
+
+
+def demangle_locals_in_text(text: str) -> str:
+ return _MANGLED_LOCAL_IN_TEXT_RE.sub(r"\1", text)
diff --git a/marimo/_runtime/pytest.py b/marimo/_runtime/pytest.py
index a8bc8ce6d4..e9535d9ca6 100644
--- a/marimo/_runtime/pytest.py
+++ b/marimo/_runtime/pytest.py
@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any
from marimo._ast.cell import Cell
from marimo._ast.pytest import MARIMO_TEST_STUB_NAME
+from marimo._ast.variables import demangle_locals_in_text
from marimo._cli.print import bold, green
from marimo._dependencies.dependencies import DependencyManager
from marimo._runtime.capture import capture_stdout
@@ -82,6 +83,30 @@ def _to_marimo_uri(uri: str) -> str:
return f"marimo://{notebook}#cell_id={cell_id}"
+def _rewrite_longrepr(longrepr: Any) -> None:
+ """Rewrite a TerminalRepr in place for user-friendly test output.
+
+ Strips the parameter-workaround frame at the top of the traceback,
+ rewrites each entry's file location into a `marimo://` URI, and
+ demangles `_cell_<id>_<name>` -> `<_name>` in source/exception lines
+ and the short-summary `reprcrash.message`.
+ """
+ if "func_JYWB" in str(longrepr):
+ longrepr.reprtraceback.reprentries = (
+ longrepr.reprtraceback.reprentries[1:]
+ )
+ for entry in longrepr.reprtraceback.reprentries:
+ if entry.reprfileloc is not None:
+ entry.reprfileloc.path = _to_marimo_uri(entry.reprfileloc.path)
+ if getattr(entry, "lines", None):
+ entry.lines = [
+ demangle_locals_in_text(line) for line in entry.lines
+ ]
+ reprcrash = getattr(longrepr, "reprcrash", None)
+ if reprcrash is not None and reprcrash.message:
+ reprcrash.message = demangle_locals_in_text(reprcrash.message)
+
+
def _sub_function(
old_item: _pytest.Item, parent: Any, fn: Callable[..., Any]
) -> _pytest.Item:
@@ -313,19 +338,9 @@ class ReplaceStubPlugin:
if isinstance(report.longrepr, tuple):
_, lineno, msg = report.longrepr
report.longrepr = (report.nodeid, lineno, f"({msg})")
- # Not all TerminalRepr seem to have a reprtraceback
+ # Not all TerminalRepr seem to have a reprtraceback.
elif hasattr(report.longrepr, "reprtraceback"):
- longrepr = str(report.longrepr)
- if "func_JYWB" in longrepr:
- # Strip the first call of traceback
- report.longrepr.reprtraceback.reprentries = (
- report.longrepr.reprtraceback.reprentries[1:]
- )
- for entry in report.longrepr.reprtraceback.reprentries:
- if entry.reprfileloc is not None:
- entry.reprfileloc.path = _to_marimo_uri(
- entry.reprfileloc.path
- )
+ _rewrite_longrepr(report.longrepr)
def run_pytest(
diff --git a/tests/_ast/test_demangle_locals.py b/tests/_ast/test_demangle_locals.py
new file mode 100644
index 0000000000..a8a31e4cf9
--- /dev/null
+++ b/tests/_ast/test_demangle_locals.py
@@ -0,0 +1,51 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from marimo._ast.variables import demangle_locals_in_text
+
+
+def test_demangle_in_name_error_message() -> None:
+ assert (
+ demangle_locals_in_text(
+ "NameError: name '_cell_vblA_a' is not defined"
+ )
+ == "NameError: name '_a' is not defined"
+ )
+
+
+def test_demangle_handles_multi_segment_names() -> None:
+ assert (
+ demangle_locals_in_text("_cell_AAAA_x and _cell_BBBB_y_z")
+ == "_x and _y_z"
+ )
+
+
+def test_demangle_leaves_cell_file_path_alone() -> None:
+ path = "/tmp/marimo_42/__marimo__cell_Hbol_.py"
+ assert demangle_locals_in_text(path) == path
+
+
+def test_demangle_no_op_for_plain_text() -> None:
+ assert demangle_locals_in_text("plain text") == "plain text"
+
+
+def test_demangle_handles_uuid_cell_id() -> None:
+ # External / VSCode notebooks use `external_prefix()` (a uuid4) as the
+ # cell-id prefix, producing hyphenated mangles.
+ assert (
+ demangle_locals_in_text(
+ "NameError: name "
+ "'_cell_c9bf9e57-1685-4c89-bafb-ff5af830be8a_a' "
+ "is not defined"
+ )
+ == "NameError: name '_a' is not defined"
+ )
+
+
+def test_demangle_handles_single_underscore_local() -> None:
+ # `_` is a valid local name (variables.py:is_local); it mangles to
+ # `_cell_<id>_` with no name suffix.
+ assert (
+ demangle_locals_in_text("NameError: name '_cell_Hbol_' is not defined")
+ == "NameError: name '_' is not defined"
+ )