Skip to content

Troubleshooting ​

Import domain exceptions from pymalloy.errors. Use the symptom to choose the next check:

SymptomCause to inspectNext action
CompilationErrorInvalid source, unresolved name, or missing schemaRead error.diagnostics or run pymalloy check PATH --json
CompilationError caused by SchemaErrorThe engine failed a schema probeInspect error.__cause__.sql and its original cause, then check the connection and files
ExecutionErrorSQL compiled but the engine rejected executionRetain error.context and error.__cause__, then replay with the same data and settings
ClosedErrorA connection or model was closedCreate a connection or compile another model
CompilerErrorEmbedded compiler or boundary validation failedRetain diagnostics and compile another model
ValidationErrorA check failed or strict warnings were rejectedRead error.report.checks and its counterexamples before revising the definition
TimeoutError during SQLThe statement exceeded its budgetReduce the query or increase timeout, then reuse a healthy model
TimeoutError during compiler workAn active compiler request exceeded its budgetCompile another model
Missing or wrong fileImport URL, process directory, and data search path differInspect each separately and use absolute paths to disambiguate
Widget fails to loadPackaged assets or browser worker policyInspect widget.bundle_status and browser errors
Widget query failsSource diagnostics, data URL, or network permissionInspect widget.state["error"] and diagnostics
Native API requested in PyodideA synchronous native entry point was selectedUse pymalloy.browser.connect() and await browser operations

Diagnose file access ​

DuckDB, the SQL engine, checks the current process directory before file_search_path. Malloy imports resolve from the model URL. A borrowed connection keeps the caller's settings. See data access.

Remote files and WebAssembly runtime assets need reachable URLs and cross-origin resource sharing permission. Declare SQL-reader files explicitly when exporting notebooks.

Recover runtime and notebook state ​

A SQL timeout can abort an explicit borrowed transaction. The connection owner must roll it back. A queued timeout leaves the active operation running. Compiler failure closes the affected model. Browser worker death requires another session. Completed results remain readable.

After changing source or schema, compile another model. Replace widget mappings, such as widget.files = {**widget.files, "orders.csv": contents}, to publish a revision. See runtime errors.

After a package upgrade or class edits in an editable install, save the notebook and restart its kernel. Automatic module reload can mix expression class versions. An error asking for col(), lit(), or Expr.raw() on a value created with pm.col() can indicate this mismatch. Rerunning an import can retain existing class references in other cells.