Troubleshooting¶

This guide covers common issues and unexpected behaviors you might encounter when using marimo notebooks, along with ways to debug and resolve them. If your issue isn’t covered here, try checking our FAQ.

Why aren’t my cells running?¶

If you’re expecting cells to run in response to changes in other cells, but they’re not, consider the following:

Check for mutations¶

marimo doesn’t track mutations to objects. If you’re modifying an object in one cell and expecting another cell to react, this won’t work as expected.

Instead of mutating objects across cells, try creating new objects or performing all mutations within the same cell.

Verify cell connections¶

Use the Dependency Panel or Variable Panel to check if your cells are actually connected as you expect.

Open the Dependency Panel (graph icon) or Variable Panel (variable icon) in the left sidebar.
Look for arrows connecting your cells or check which cells are listed as using each variable.
If connections are missing, review your variable usage to ensure cells are properly referencing each other.

Dependency graph showing cell connections.

Why is my cell running unexpectedly?¶

If a cell is running more often than you anticipate:

Check cell dependencies¶

Use the Dependency Panel or Variable Panel to see what’s triggering your cell:

Open the Dependency Panel or Variable Panel.
Locate your cell and examine its incoming connections.
You might find unexpected dependencies that are causing the cell to run.

Understand global vs local variables vs functions args¶

Ensure you’re not inadvertently using a global variables when intending to use a local variable or function argument:

Check for any variables used in your cell that aren’t defined within it.
Consider using local variables (prefixed with _) for values that shouldn’t be consumed by other cells.

Why is my UI element’s value being reset?¶

If a UI element’s value keeps resetting:

Check that cell defining the UI element isn’t rerunning¶

If the cell defining the UI element reruns, it will reset the element’s value to its initial value argument. You may be able to avoid this by splitting the UI element definition into a separate cell.

Use state for persistence¶

If you need to maintain UI element values across cell runs, consider using mo.state:

# Declare state in a separate cell
get_value, set_value = mo.state(initial_value)

element = mo.ui.slider(0, 10, value=get_value(), on_change=set_value)

This way, the value persists even if the cell defining the element reruns.

How can I force one cell to run after another?¶

If you need to ensure a specific execution order:

Use explicit dependencies¶

Create an explicit dependency by using a variable from the first cell in the second:

# Cell 1
result = some_computation()

# Cell 2
_ = result  # This creates a dependency on Cell 1
further_computation()

Consider refactoring¶

If you find yourself needing to force execution order often, it might be a sign that your notebook structure could be improved:

Try to organize your cells so that natural data flow creates the desired order.
Consider combining related operations into single cells where appropriate.

General debugging tips¶

Use the Variables Panel to inspect variable values and see where they’re defined and used.
Add print statements or use mo.md() to output debug information in cell outputs.
Temporarily disable cells to isolate issues.
Use the “Lazy” runtime configuration to see which cells are being marked as stale without automatically running them.

Remember, marimo’s reactivity is based on global variable definitions and references, and mutations to objects aren’t tracked. Keeping this in mind can help you understand and debug unexpected behaviors in your notebooks.

Why is the notebook returning 404s on the web assets?¶

If you’re seeing 404 errors for web assets like JS or CSS files, it may be due to symlink settings or proxy settings.

Check symlink settings¶

If you are using bazel or uv’s link-mode: symlink, you may need to adjust your symlink settings to ensure that web assets are correctly found. By default marimo does not follow symlinks, so you may need to turn this setting on.

Locate your marimo.toml configuration file with marimo config show, and edit the follow_symlink flag:

[server]
follow_symlink = true

Check proxy settings¶

If you are using a proxy server, you need to include the --proxy flag when running marimo. The proxy will default to port 80 if no port is specified. For example, if your proxy is example.com and it uses port 8080, you would run:

marimo edit --proxy example.com:8080
# or
marimo run --proxy example.com:8080