Why am I getting a "Java class not found" error when starting deephaven-server?

The problem

You see an error like this when running deephaven server:

ValueError: Java class 'io.deephaven.python.server.EmbeddedServer' not found

This cryptic error message typically indicates that you're using an incompatible Java version.

The solution

You must use Java 17 or later when running deephaven-server version 0.36.0 and above.

The Deephaven server wheel requires Java 17+ because:

• Jetty 12 (used by Deephaven) requires Java 17 or later.
• Jetty 11 reached end-of-life, prompting the upgrade.

How to Fix

1. Check your Java version:

   java -version
   

2. Install Java 17 or later if needed:

   On Ubuntu/Debian:

   apt-get install openjdk-17-jdk
   

   On macOS:

   brew install openjdk@17
   

3. Ensure Java 17 is being used by your environment before starting the server:

   Verify the active Java version:

   java -version
   

   If you have multiple Java versions installed, set JAVA_HOME to point to Java 17:

   On Linux/macOS:

   export JAVA_HOME=/path/to/java17
   export PATH=$JAVA_HOME/bin:$PATH
   

   On macOS with Homebrew:

   export JAVA_HOME=/usr/local/opt/openjdk@17
   export PATH=$JAVA_HOME/bin:$PATH
   

   On Windows (Command Prompt):

   set JAVA_HOME=C:\Path\To\Java17
   set PATH=%JAVA_HOME%\bin;%PATH%
   

   On Windows (PowerShell):

   $env:JAVA_HOME = "C:\Path\To\Java17"
   $env:PATH = "$env:JAVA_HOME\bin;$env:PATH"
   

   To make these changes permanent, add them to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile).

Example Dockerfile

If you're using Docker, make sure to install the correct Java version:

FROM ubuntu:24.04

RUN apt-get update && \
    apt-get install -y software-properties-common && \
    add-apt-repository ppa:deadsnakes/ppa && \
    apt-get update

RUN apt-get install -y \
    python3.12 \
    python3.12-venv \
    python3.12-dev \
    g++ \
    openjdk-17-jdk  # Use Java 17, not Java 11

# Create and activate virtual environment
RUN python3.12 -m venv /venv
RUN /venv/bin/pip install deephaven-server

# Start server
CMD ["/venv/bin/deephaven", "server"]

Additional Notes

• The deephaven-core wheel (for client-side use) does not require Java to be installed.
• The deephaven-server wheel requires Java 17+ to be available in your environment.
• When creating a Server instance in Python (e.g., from deephaven_server.server import Server), you must have Java 17+ installed and available.