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.

Improve anywidget invalid module error messages (#10026)

Shahmir Varqha82a0ef6ad551
diff --git a/frontend/src/components/data-table/utils.ts b/frontend/src/components/data-table/utils.ts
index 96b92f9aaa..330902599d 100644
--- a/frontend/src/components/data-table/utils.ts
+++ b/frontend/src/components/data-table/utils.ts
@@ -4,6 +4,7 @@ import type { Table } from "@tanstack/react-table";
import type { TableData } from "@/plugins/impl/DataTablePlugin";
import { vegaLoadData } from "@/plugins/impl/vega/loader";
import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
+import { isRecord } from "@/utils/records";
import { getMimeValues } from "./mime-cell";
import type { DataType } from "@/core/kernel/messages";
import {
@@ -232,10 +233,6 @@ function stripHtml(html: string): string {
const HTML_MIMETYPES = new Set(["text/html", "text/markdown"]);
-function isRecord(value: unknown): value is Record<string, unknown> {
- return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
/**
* Get clipboard-ready text and optional HTML for a cell.
*
diff --git a/frontend/src/core/islands/parse.ts b/frontend/src/core/islands/parse.ts
index 8e8e4d3c66..6662b70f66 100644
--- a/frontend/src/core/islands/parse.ts
+++ b/frontend/src/core/islands/parse.ts
@@ -6,6 +6,7 @@ import {
ISLANDS_JSON_SCRIPT_TYPE,
} from "@/core/islands/constants";
import { Logger } from "@/utils/Logger";
+import { isRecord } from "@/utils/records";
/**
* DOM elements look like this:
@@ -480,7 +481,3 @@ function isMarimoIslandPayloadCell(
typeof cell.displayOutput === "boolean"
);
}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
- return typeof value === "object" && value !== null;
-}
diff --git a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
index 0e9080b531..6a023ae9ee 100644
--- a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
+++ b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
@@ -10,6 +10,7 @@ import { createPlugin } from "@/plugins/core/builder";
import type { IPluginProps } from "@/plugins/types";
import { prettyError } from "@/utils/errors";
import { Logger } from "@/utils/Logger";
+import { hasFunctionProperty, isRecord } from "@/utils/records";
import { ErrorBanner } from "../common/error-banner";
import { getMarimoInternal, MODEL_MANAGER, type Model } from "./model";
import type { ModelState, WidgetModelId } from "./types";
@@ -140,10 +141,9 @@ const AnyWidgetSlot = (props: IPluginProps<ModelIdRef, Data>) => {
}
if (!isAnyWidgetModule(jsModule)) {
- const error = new Error(
- `Module at ${jsUrl} does not appear to be a valid anywidget`,
+ return (
+ <ErrorBanner error={getInvalidAnyWidgetModuleError(jsModule, jsUrl)} />
);
- return <ErrorBanner error={error} />;
}
return (
@@ -200,6 +200,52 @@ function isAnyWidgetModule(mod: any): mod is { default: AnyWidget } {
);
}
+function getInvalidAnyWidgetModuleError(mod: unknown, jsUrl: string): Error {
+ const afmDocs = "https://anywidget.dev/en/afm/";
+ const hasNamedRender = isRecord(mod) && hasFunctionProperty(mod, "render");
+ const hasNamedInitialize =
+ isRecord(mod) && hasFunctionProperty(mod, "initialize");
+
+ if (hasNamedRender || hasNamedInitialize) {
+ const namedExports = [
+ hasNamedRender ? "`render`" : null,
+ hasNamedInitialize ? "`initialize`" : null,
+ ]
+ .filter(Boolean)
+ .join(" and ");
+ const lifecycleHooks = [
+ hasNamedRender ? "render" : null,
+ hasNamedInitialize ? "initialize" : null,
+ ].filter((hook): hook is string => hook !== null);
+ const defaultExportExample = `export default { ${lifecycleHooks.join(", ")} }`;
+ const namedExportExample =
+ lifecycleHooks.length === 1
+ ? `export function ${lifecycleHooks[0]}`
+ : "named export function ...";
+ return new Error(
+ `Anywidget module at ${jsUrl} uses named exports (${namedExports}). ` +
+ "Per the AFM spec, use a default export instead: " +
+ `\`${defaultExportExample}\` (not \`${namedExportExample}\`). ` +
+ `See ${afmDocs}`,
+ );
+ }
+
+ if (!isRecord(mod) || mod.default === undefined) {
+ return new Error(
+ `Anywidget module at ${jsUrl} is missing a default export. ` +
+ "Per the AFM spec, use `export default { render }` or " +
+ "`export default async () => ({ render })`. " +
+ `See ${afmDocs}`,
+ );
+ }
+
+ return new Error(
+ `Anywidget module at ${jsUrl} has an invalid default export. ` +
+ "Expected a factory function or an object with `render` or `initialize`. " +
+ `See ${afmDocs}`,
+ );
+}
+
interface Props<T extends AnyWidgetState> {
widget: AnyWidget<T>;
modelId: WidgetModelId;
@@ -250,4 +296,5 @@ export const visibleForTesting = {
LoadedSlot,
runAnyWidgetModule,
isAnyWidgetModule,
+ getInvalidAnyWidgetModuleError,
};
diff --git a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx
index a6e080cc56..94d3785ff3 100644
--- a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx
+++ b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx
@@ -9,7 +9,8 @@ import { MODEL_MANAGER, Model } from "../model";
import type { WidgetModelId } from "../types";
import { BINDING_MANAGER } from "../widget-binding";
-const { LoadedSlot } = visibleForTesting;
+const { LoadedSlot, isAnyWidgetModule, getInvalidAnyWidgetModuleError } =
+ visibleForTesting;
// Helper to create typed model IDs for tests
const asModelId = (id: string): WidgetModelId => id as WidgetModelId;
@@ -150,3 +151,71 @@ describe("LoadedSlot", () => {
});
});
});
+
+describe("isAnyWidgetModule", () => {
+ it("should accept a default object with render", () => {
+ expect(isAnyWidgetModule({ default: { render: () => undefined } })).toBe(
+ true,
+ );
+ });
+
+ it("should accept a default factory function", () => {
+ expect(
+ isAnyWidgetModule({ default: async () => ({ render: () => {} }) }),
+ ).toBe(true);
+ });
+
+ it("should reject legacy named render exports", () => {
+ expect(isAnyWidgetModule({ render: () => undefined })).toBe(false);
+ });
+});
+
+describe("getInvalidAnyWidgetModuleError", () => {
+ const jsUrl = "./@file/widget.js";
+
+ it("should explain legacy named render exports", () => {
+ const error = getInvalidAnyWidgetModuleError(
+ { render: () => undefined },
+ jsUrl,
+ );
+ expect(error.message).toContain("named exports (`render`)");
+ expect(error.message).toContain("`export default { render }`");
+ expect(error.message).toContain("not `export function render`");
+ });
+
+ it("should explain legacy named initialize exports", () => {
+ const error = getInvalidAnyWidgetModuleError(
+ { initialize: () => undefined },
+ jsUrl,
+ );
+ expect(error.message).toContain("named exports (`initialize`)");
+ expect(error.message).toContain("`export default { initialize }`");
+ expect(error.message).toContain("not `export function initialize`");
+ });
+
+ it("should avoid nested backticks for multi-hook named exports", () => {
+ const error = getInvalidAnyWidgetModuleError(
+ { render: () => undefined, initialize: () => undefined },
+ jsUrl,
+ );
+ expect(error.message).toContain(
+ "`export default { render, initialize }` (not `named export function ...`).",
+ );
+ expect(error.message).not.toContain("`named `export");
+ });
+
+ it("should explain a missing default export", () => {
+ expect(getInvalidAnyWidgetModuleError({}, jsUrl).message).toContain(
+ "missing a default export",
+ );
+ expect(getInvalidAnyWidgetModuleError(null, jsUrl).message).toContain(
+ "missing a default export",
+ );
+ });
+
+ it("should explain an invalid default export", () => {
+ const error = getInvalidAnyWidgetModuleError({ default: {} }, jsUrl);
+ expect(error.message).toContain("invalid default export");
+ expect(error.message).toContain("https://anywidget.dev/en/afm/");
+ });
+});
diff --git a/frontend/src/utils/__tests__/records.test.ts b/frontend/src/utils/__tests__/records.test.ts
new file mode 100644
index 0000000000..b624892f0a
--- /dev/null
+++ b/frontend/src/utils/__tests__/records.test.ts
@@ -0,0 +1,27 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import { hasFunctionProperty, isRecord } from "../records";
+
+describe("isRecord", () => {
+ it("should accept plain objects", () => {
+ expect(isRecord({})).toBe(true);
+ expect(isRecord({ a: 1 })).toBe(true);
+ });
+
+ it("should reject null, arrays, and primitives", () => {
+ expect(isRecord(null)).toBe(false);
+ expect(isRecord([])).toBe(false);
+ expect(isRecord("x")).toBe(false);
+ expect(isRecord(1)).toBe(false);
+ });
+});
+
+describe("hasFunctionProperty", () => {
+ it("should detect function properties", () => {
+ expect(hasFunctionProperty({ render: () => undefined }, "render")).toBe(
+ true,
+ );
+ expect(hasFunctionProperty({ render: 1 }, "render")).toBe(false);
+ });
+});
diff --git a/frontend/src/utils/records.ts b/frontend/src/utils/records.ts
new file mode 100644
index 0000000000..73341b5060
--- /dev/null
+++ b/frontend/src/utils/records.ts
@@ -0,0 +1,12 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function hasFunctionProperty(
+ record: Record<string, unknown>,
+ key: string,
+): boolean {
+ return typeof record[key] === "function";
+}