> ## Documentation Index
> Fetch the complete documentation index at: https://catalyst.leifiyo.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Java runtimes

> How Catalyst detects, downloads, and assigns Java runtimes for Minecraft servers.

Catalyst can use Java installed on the system, Java from `JAVA_HOME`, Java found on `PATH`, common platform install locations, managed Catalyst runtimes, or a per-server custom executable.

## Version mapping

| Minecraft version     | Required Java |
| --------------------- | ------------- |
| 1.20.5 and newer      | Java 21       |
| 1.17 through 1.20.4   | Java 17       |
| 1.12 through 1.16.5   | Java 11       |
| 1.7.10 through 1.11.2 | Java 8        |

## Runtime selection order

<Steps>
  <Step title="Use custom Java when set">
    A server-specific Java executable path takes priority.
  </Step>

  <Step title="Search installed runtimes">
    Catalyst checks managed runtimes, `JAVA_HOME`, `PATH`, and common install directories.
  </Step>

  <Step title="Download if needed">
    When no compatible runtime is found, Catalyst can download an Adoptium JDK for the required major version.
  </Step>

  <Step title="Start with matching JAVA_HOME">
    Managed or custom runtimes set the process environment so Java tools resolve consistently.
  </Step>
</Steps>

## Managed runtimes

Managed runtimes are stored under:

```text theme={null}
userData/runtimes/
```

Downloads use the Adoptium binary API and include timeout, stall, extraction, and checksum handling when the upstream response provides checksum information.

<Info>
  Changing a server's Java path does not affect running processes. Restart the server after saving the setting.
</Info>