# Atlas update fails with "checksum mismatch; aborting" or a failed release download > Re-run the update first, since a truncated download is the most common cause of a checksum mismatch, then check for a proxy that rewrites or caches binaries. Atlas fails an update with "checksum mismatch; aborting" because installation/syntora.ts downloads the release artifact for your platform and compares its SHA-256 against artifact.sha256, aborting on any mismatch. Re-run the update first: a truncated download is the most common cause of a checksum mismatch. If it keeps failing, check for a proxy that rewrites or caches binaries, because that will corrupt the artifact deterministically and every retry will fail the same way. ## Symptom Updating Atlas fails with one of: checksum mismatch; aborting. Or: download failed (). Or: no build available for . Or: Atlas release manifest unavailable (). The update aborts and Atlas stays on the installed version. ## Cause Atlas installation/syntora.ts fetches the release manifest, selects the artifact for the current platform, downloads it, and compares the SHA-256 against artifact.sha256, aborting on any mismatch. A truncated download or a proxy that rewrites binaries produces a hash that does not match. ## Fix 1. Re-run the update: a truncated download is the most common cause of a checksum mismatch. 2. Check for a proxy that rewrites or caches binaries; that will corrupt the artifact deterministically. 3. If the platform has no artifact, install via a package manager instead of the self-updater. 4. A 401 or 403 from the manifest raises "Atlas update authentication failed. Run: atlas login"; log in and retry. ## Why does Atlas report checksum mismatch; aborting Atlas reports "checksum mismatch; aborting" because installation/syntora.ts downloads the release artifact and compares its SHA-256 against artifact.sha256 from the release manifest. Any mismatch aborts the update, because a binary whose hash does not match is a binary Atlas will not run. The SHA-256 comparison is the last gate in a 4-step sequence: Atlas fetches the release manifest, selects the artifact for the current platform, downloads it, and hashes the result. A mismatch means the bytes that arrived are not the bytes the manifest promised. That is almost never a signing problem and almost always a transport problem. Atlas aborts rather than installing a binary of unknown provenance, which is the correct behavior for a self-updater. The message names the failure precisely so you can act on the download path rather than on Atlas itself. ## How to fix an Atlas checksum mismatch Fix an Atlas checksum mismatch by re-running the update first. A truncated download is the most common cause of a mismatch between the artifact's SHA-256 and artifact.sha256, and a second attempt over a healthy connection usually completes and hashes correctly on the first retry. Retry once before you investigate. A dropped connection, a flaky network segment, or an interrupted transfer produces a partial file whose hash cannot possibly match, and the fix costs nothing. If the retry succeeds, the cause was transient and you are done. If the retry fails with the same "checksum mismatch; aborting" message, stop retrying: a repeatable mismatch means something is corrupting the artifact the same way every time, and the next thing to examine is your network path rather than your download luck. ## Why a proxy causes a repeatable Atlas checksum mismatch A proxy that rewrites or caches binaries will corrupt the Atlas artifact deterministically, which is why a checksum mismatch that survives every retry points at the network path. The SHA-256 Atlas computes will differ from artifact.sha256 identically on every attempt, because the same proxy makes the same modification. Corporate proxies, TLS-inspecting middleboxes, and caching layers routinely alter or serve stale copies of binary downloads. Any byte-level modification, including a well-intentioned one, breaks the SHA-256 check in installation/syntora.ts. The tell is repeatability: a truncated download fails differently each time, while a proxy fails the same way every time. If retries produce identical failures, look at what sits between the machine running Atlas and the release host, and either exempt the release download from the proxy or run the update from a network path that does not traverse it. ## What no build available for means in Atlas Atlas prints "no build available for " when the release manifest has no artifact matching your current platform, so installation/syntora.ts had nothing to select and nothing to download. No SHA-256 checksum was ever computed, and retrying the self-updater produces the same message every time. Install via a package manager instead. The remedy differs from every other failure on this page. If the platform has no artifact, install via a package manager instead of the self-updater. Retrying, clearing caches, or bypassing a proxy will not conjure a build that the manifest does not list. Read the platform string in the message and confirm it is the one you expect, because an unexpected platform value can point at an environment problem, such as running Atlas under an architecture you did not intend. Then switch to a package manager install for that platform. ## How to fix Atlas release manifest unavailable and authentication failures "Atlas release manifest unavailable ()" means installation/syntora.ts could not fetch the release manifest at all. When the status is a 401 or 403, Atlas raises "Atlas update authentication failed. Run: atlas login" instead, and the fix is to run `atlas login` and retry the update. The manifest fetch happens before the artifact is selected, so a manifest failure means the update never got as far as downloading anything. Read the status code in the parentheses. A 401 or 403 is an authentication problem, and Atlas tells you exactly what to do about it: run `atlas login`, then retry. Any other status is a transport or availability problem with the manifest itself, and a retry is reasonable there too. Do not confuse a manifest failure with a checksum mismatch: the two happen at different stages and have unrelated fixes. ## How to verify the Atlas update fix worked Verify the Atlas update fix by re-running the update and watching for the absence of all 4 failure strings: checksum mismatch; aborting, download failed (), no build available for , and Atlas release manifest unavailable (). A clean update means the SHA-256 matched artifact.sha256. Verify from the same machine and the same network that produced the failure, because a proxy-induced corruption disappears the moment you switch networks and reappears the moment you switch back. If the mismatch is gone, installation/syntora.ts hashed the downloaded artifact, matched it against artifact.sha256, and installed it. If a different message now appears, you have cleared the checksum stage and hit an earlier or later one, so read the new string and match it to the fix that belongs to it. ## FAQ ### How do I fix "checksum mismatch; aborting" when updating Atlas? Re-run the update first, since a truncated download is the most common cause of a checksum mismatch. If the mismatch repeats identically, check for a proxy that rewrites or caches binaries. ### Why does Atlas check a checksum on update? Atlas installation/syntora.ts downloads the release artifact and compares its SHA-256 against artifact.sha256 from the release manifest, aborting on any mismatch rather than installing a binary whose bytes do not match. ### Why does my Atlas checksum mismatch happen every single time? A repeatable mismatch points at a proxy that rewrites or caches binaries, which corrupts the artifact deterministically. A truncated download fails differently each time; a proxy fails the same way every time. ### What does "no build available for " mean in Atlas? The Atlas release manifest has no artifact for your current platform. Install via a package manager instead of the self-updater, because retrying will not produce a build the manifest does not list. ### What does "Atlas release manifest unavailable" mean? Atlas could not fetch the release manifest, and the status code is shown in parentheses. The manifest fetch happens before any download, so no artifact was selected and no checksum was computed. ### How do I fix "Atlas update authentication failed"? A 401 or 403 from the manifest raises "Atlas update authentication failed. Run: atlas login". Run `atlas login` and retry the update. ### What does "download failed" with a status mean in an Atlas update? "download failed ()" means the artifact download itself did not complete successfully, so Atlas never got to compare the SHA-256 against artifact.sha256. Read the status and retry the update. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/release-download-checksum-mismatch Source of truth: aeo_pages row `/resources/troubleshooting/release-download-checksum-mismatch` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.