Skip to content
rexenv

A component won't download

rexenv downloads its components on demand and verifies each one against a recorded SHA-256 before allowing it to run. Two different failures look similar from the outside.

The download failed

Section titled “The download failed”

A network problem, a proxy, or an upstream that is temporarily down. Retrying is the right response, and rexenv retries the step rather than the whole operation.

If it keeps failing, check whether the upstream is reachable at all:

Terminal window
curl -sI https://github.com | head -1

Corporate proxies and VPNs that intercept TLS are the common cause. rexenv uses the system trust store, so a proxy whose certificate your Mac already trusts works.

The checksum did not match

Section titled “The checksum did not match”

Different problem, and the download is not retried into use. A mismatch means the bytes on disk are not the bytes that were pinned, and rexenv refuses rather than running them.

Causes, roughly in order of likelihood:

  • A truncated or corrupted download — retry.
  • A proxy or captive portal returning an HTML error page in place of the file — the “binary” is a login page. Get off the portal and retry.
  • The upstream re-published an artefact under the same URL. Real, and a rexenv bug to fix by re-pinning, not something to work around locally.

This check is not paranoia theatre: it is the difference between a failed download and a silently substituted binary running on your machine with your permissions.

A pin returned 404

Section titled “A pin returned 404”

rexenv pins content-addressed URLs where upstreams offer them, so a pin can disappear but can never drift — the pinned artefact either exists unchanged or is gone.

Homebrew garbage-collects old bottles, so a 404 on a pinned URL is expected eventually and is fixed by a rexenv release that re-pins. Worth reporting with the exact component and version from the error.

Disk space

Section titled “Disk space”

A full disk shows up as a failed download or an unpack error. A working setup wants 2–4GB — see Requirements.

Starting over on one component

Section titled “Starting over on one component”

Components live under ~/Library/Application Support/dev.rexenv.rexenv/. Deleting a single component’s directory makes rexenv fetch it again the next time it is needed. Deleting the whole directory removes your sites and databases too — check before you reach for it.