Solara Server

Common errors

• ERROR: Exception in ASGI application ...... ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:1129)

  cause This error, often accompanied by long loading times, can occur when Solara tries to access CDNs for assets even after `solara[assets]` has been installed, particularly in environments with strict network policies or self-signed certificates.
  fix Ensure all required assets are bundled locally by installing with `pip install "solara[assets]"`. If the issue persists, it might indicate an underlying network or certificate configuration problem that prevents local asset resolution or external CDN access.

• Solara app in Jupyter notebook does not display, or interactive components are not responsive.

  cause The most common cause is a discrepancy in Python environments, where the Jupyter notebook server and the kernel are using different installations, and required JavaScript dependencies (like ipyvue, ipyvuetify) are not available in the server's environment.
  fix Install `solara ipyvue ipyvuetify` (or simply `solara`) in the Python environment *used by the Jupyter server itself*, not just the kernel. You might need to identify the server's Python executable path and use it to install the packages.

• Starlette 1.0 breaks Solara import: Starlette.__init__() no longer accepts on_startup / on_shutdown.

  cause An incompatibility with Starlette version 1.0 where the `__init__` method of Starlette applications has removed the `on_startup` and `on_shutdown` parameters, which Solara Server's integration expects.
  fix Downgrade Starlette to a version prior to 1.0 (e.g., `pip install 'starlette<1.0'`). This issue will require an update from the Solara development team for full Starlette 1.0 compatibility.

Warnings

• breaking Solara 2.0 (planned release end of year) introduces significant changes to reactive state management, including default state mutation detection and altered behavior for reactive variables in boolean comparisons. These changes can be enabled in Solara >= 1.41.0/1.42.0 via environment variables but will be default in 2.0.
  Fix: Review the Solara 2.0 roadmap and documentation for details on reactive state management changes. Enable `SOLARA_STORAGE_MUTATION_DETECTION=1` or `SOLARA_ALLOW_REACTIVE_BOOLEAN=0` in current versions to test compatibility.
• breaking Integration with Starlette 1.0 is currently broken as `Starlette.__init__()` no longer accepts `on_startup` or `on_shutdown` arguments.
  Fix: Pin your Starlette version to `<1.0.0` or wait for Solara to release a compatible update.
• gotcha Solara Server collects anonymous usage telemetry by default using Mixpanel. This tracks server start/stop and daily unique users/connections.
  Fix: To opt-out, set the environment variable `SOLARA_TELEMETRY_MIXPANEL_ENABLE` to `False` or include it in a `.env` file if `python-dotenv` is installed.
• gotcha When running Solara applications within Jupyter environments, a common issue is a mismatch between the Python environment of the notebook server and the kernel, leading to UI components not loading correctly (e.g., missing Javascript libraries for `ipyvue`, `ipyvuetify`).
  Fix: Ensure `ipyvue` and `ipyvuetify` (and `solara`) are installed in the *same* Python environment that both your Jupyter notebook server and the kernel are using. You may need to inspect the `!ps aux | grep jupyter` output to identify the server's Python executable.
• gotcha Solara Server keeps virtual kernels alive for 24 hours after a WebSocket disconnection by default (e.g., browser tab closed or computer hibernates). While useful for re-establishing connections, it can consume memory.
  Fix: Customize the kernel expiration duration by setting the `SOLARA_KERNEL_CULL_TIMEOUT` environment variable (e.g., `SOLARA_KERNEL_CULL_TIMEOUT=1m` for 1 minute).

Install

• pip install solara-server Base installation
• pip install "solara-server[starlette]" With Starlette integration
• pip install solara As part of the Solara meta-package (recommended for most users)

Imports

• solara run

  solara run my_app.py

  Solara Server is typically invoked via the `solara` command-line interface to run Solara applications.
• app (for embedding)
  wrong:

  from solara_server import app

  correct:

  from solara.server.starlette import app as solara_app

  When embedding Solara Server into a Starlette, FastAPI, or Flask application, you typically import the `app` object from `solara.server.<framework_name>`.

Quickstart

This quickstart demonstrates a simple Solara application with a reactive counter. Save the code as `sol.py` and run it using the `solara run` command, which starts the Solara Server.

import solara

clicks = solara.reactive(0)

@solara.component
def Page():
    def increase_clicks():
        clicks.value += 1
    solara.Button(label=f"Clicked {clicks} times", on_click=increase_clicks)

# To run this application, save it as `sol.py` and execute `solara run sol.py` in your terminal.