sbt Coursier "download error" fetch failure in CI

By Daniel Zoghalchali·Latchkey

sbt uses Coursier to fetch dependencies, and Coursier reported a download error while retrieving an artifact. Unlike "not found", this is a transport failure: a dropped connection, a slow mirror, or a proxy in the way.

What this error means

sbt update fails with "Error downloading ...: download error: Caught java.io.IOException" or "Coursier error" naming an artifact and a URL that timed out or reset.

[error]   download error: Caught java.io.IOException (Server returned HTTP response code:
503 for URL: https://repo1.maven.org/maven2/...) while downloading
https://repo1.maven.org/maven2/org/example/lib/1.0/lib-1.0.jar

Common causes

A transient upstream or mirror failure

Maven Central or a mirror returned 5xx or dropped the connection mid-transfer, so Coursier aborts that artifact.

A proxy or empty cache forces a full re-download

When ~/.coursier is not restored, every job re-fetches all artifacts, multiplying the chance a single flaky download fails the build.

How to fix it

Cache the Coursier and Ivy directories

1. Restore ~/.cache/coursier (or ~/.coursier) and ~/.ivy2 between runs.
2. Key the cache on your build definition files.
3. Re-run so most artifacts are served from cache and only new ones are fetched.

- uses: actions/cache@v4
  with:
    path: |
      ~/.ivy2/cache
      ~/.sbt
      ~/.cache/coursier
    key: sbt-${{ hashFiles('**/build.sbt','project/**') }}

Retry the resolution

A 503 or reset is usually transient. Re-running the update step or the job resolves it once the mirror recovers.

sbt update

How to prevent it

• Persist the Coursier cache so artifacts download once, not every run.
• Point Coursier at a reliable mirror close to your runners.
• Set generous timeouts when fetching through a corporate proxy.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation