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

I'm getting a cryptic ValueError: Java class 'io.deephaven.python.server.EmbeddedServer' not found error when trying to start the Deephaven server using the deephaven-server wheel. What's causing this?

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

Check your Java version:
```
java -version
```

Install Java 17 or later if needed:

On Ubuntu/Debian:

apt-get install openjdk-17-jdk

On macOS:

brew install openjdk@17

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.

Note

These FAQ pages contain answers to questions about Deephaven Community Core that our users have asked in our Community Slack. If you have a question that is not in our documentation, join our Community and we'll be happy to help!