sbt boot download failing behind a proxy in CI

Before it can build anything, sbt downloads its own boot components (the launcher, the matching sbt and Scala jars). Behind a proxy without correct settings, that bootstrap fetch fails and sbt never starts.

What this error means

sbt fails at startup with "could not retrieve sbt" / "error during sbt launcher bootstrap" or a connection error while downloading the boot jars, before any project task runs.

sbt

[error] Could not retrieve sbt 1.9.9
[error]   unresolved dependency: org.scala-sbt#sbt;1.9.9: not found
[error]   Server access error at url https://repo1.maven.org/... (Connection timed out)

Common causes

Proxy settings not passed to the sbt JVM

The runner reaches the internet only through a proxy, but the sbt launcher JVM has no http.proxyHost/https.proxyHost, so the boot download times out.

The boot repository is unreachable

A firewall blocks the default repository for the launcher and sbt jars, and no internal mirror is configured for boot resolution.

How to fix it

Pass proxy settings via SBT_OPTS

Set the JVM proxy properties in SBT_OPTS so the launcher can reach the repository.
Include nonProxyHosts for internal hosts if needed.
Re-run so the boot download succeeds through the proxy.

.github/workflows/ci.yml

env:
  SBT_OPTS: "-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=8080"

Point boot resolution at an internal mirror

Configure a repositories file so sbt resolves its launcher and boot jars from a reachable internal mirror.

~/.sbt/repositories

# ~/.sbt/repositories
[repositories]
  local
  my-mirror: https://nexus.example.com/repository/maven-public/

How to prevent it

Set JVM proxy properties in SBT_OPTS on proxied runners.
Configure an internal repositories mirror for boot resolution.
Cache ~/.sbt/boot so the launcher is not re-fetched each run.