# Upgrade a Dependency and Fix the Breakage with Atlas (2026 Workflow)

> Atlas reads the real compiler output rather than assuming what broke, and webfetch pulls the release notes so the fixes match the actual breaking changes.

To bump a library to a new major version and repair every compile and test failure it causes, let Atlas drive the package manager through bash, read the real compiler output rather than assuming what broke, and fix the callsites with edit. Atlas runs the package manager upgrade through bash and captures the full output, and if the output exceeds the limits it is saved to a file you can read. Atlas then fetches the library's release notes with webfetch so the breaking changes are in context before you start editing, builds or typechecks with bash and lets the compiler enumerate the breakage, and uses the lsp tool's goToDefinition operation to inspect the new signatures in the upgraded package.

## Key takeaways

- Never predict the breakage. Build or typecheck with bash and let the compiler enumerate exactly what broke in your codebase.
- webfetch pulls the release notes so the fixes match the actual breaking changes, including the ones that produce no compiler error at all.
- The lsp tool's goToDefinition shows the signature that is actually installed, which outranks documentation, changelogs, and memory.
- A bash upgrade that overflows the output limits is saved to a file the read tool can open, so no resolver output is lost.
- Green tests are necessary and not sufficient. Review the whole diff before committing so no fix is a suppression.

## How do I upgrade a dependency and fix everything it breaks with Atlas?

Atlas upgrades a dependency in 5 steps: bash runs the package manager upgrade, webfetch pulls the library's release notes, bash builds or typechecks to enumerate the breakage, edit fixes each error using the lsp tool's goToDefinition to inspect the new signatures, and bash re-runs build and tests until clean.

The upgrade sequence is built around one rule: never predict the breakage. A major version bump breaks things the changelog does not mention and leaves things alone that the changelog implies it will break. Atlas builds first and reads the real compiler output, which is the only accurate list of what actually broke in your codebase, as opposed to what a library upgrade breaks in general. The release notes are context for the fixes, not a substitute for the compiler's error list.

## How does Atlas run a package manager upgrade through bash?

Atlas runs the package manager upgrade through bash and captures the full output. If the output exceeds the limits it is saved to a file you can read, which matters on a v3 to v4 bump, where the resolver prints hundreds of lines of transitive dependency changes nobody wants truncated.

The package manager upgrade is a permission-gated bash call, like every Atlas tool call, checked against allow, ask, and deny rules before it runs. A dependency upgrade is exactly the kind of command most teams leave on ask, because it rewrites the lockfile. Capturing the full package manager output is what makes the next steps possible: the resolver's own report of which transitive dependencies it moved, including bumps you never requested, is frequently the explanation for a compile failure that has nothing to do with the library you named on the upgrade command line.

## Why does Atlas fetch release notes with webfetch before fixing errors?

Atlas fetches the library's release notes with webfetch so the breaking changes are in context before you start editing. Without the changelog, a fix for a v3 to v4 bump is a guess, and a guess that compiles is the worst possible outcome, because it passes the build and changes the behavior.

A compiler error tells you that a call no longer typechecks. The library's changelog tells you why, and what the maintainer intends you to do instead. The difference shows up in the fixes: a renamed option is a mechanical substitution, but an option whose default value flipped between major versions is a silent behavior change that produces no compiler error at all. Pulling the release notes with webfetch before editing means the fixes match the actual breaking changes in the changelog instead of a guess, which is how the upgrade catches the breakage the compiler cannot see.

## Should I predict what a dependency upgrade will break, or build it?

Build it. Atlas builds or typechecks with bash and lets the compiler enumerate the breakage rather than predicting it, because the compiler produces the exact list for your codebase, while any prediction produces a list for a hypothetical one. A 200 error build output is a work queue.

Predicting an upgrade's breakage fails in both directions. Prediction invents work by flagging library APIs you never used, and it misses work by assuming a version change is additive when the package also tightened a type three levels down. The compiler has no such problem: the compiler reports what fails, where, and why. Atlas reads the real compiler output rather than assuming what broke, and if that build output exceeds the limits it is saved to a file the read tool can open. The compiler's error list is the upgrade plan.

## How do I check a new API signature after upgrading a package?

Atlas uses the lsp tool's goToDefinition operation to inspect the new signatures in the upgraded package. goToDefinition reads the definition that is actually installed in 2026, which is the only authoritative source once a major bump has replaced the code your editor's memory was based on.

Documentation lags, changelogs summarize, and a model's training data describes a library version that may no longer exist. The installed package does not have those problems. The lsp tool's goToDefinition jumps into the upgraded package and shows the current parameter list, the current return type, and the current overloads, which is exactly what the fix has to satisfy. Atlas fixes each compiler error with the edit tool, and Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so every upgrade fix is reviewed as it lands.

## How do I know a dependency upgrade is finished?

Atlas re-runs build and tests with bash until clean, then reviews the whole diff before committing. Green is necessary and not sufficient in a v4 major version upgrade: the tests prove the code runs, and the diff review is what proves the fixes match the changelog rather than merely silencing the compiler.

The most dangerous fix in a dependency upgrade is the one that makes an error disappear without addressing why the error existed. A cast that suppresses a tightened type. A default that was accepted implicitly and is now passed explicitly with the old value, restoring the old behavior the maintainer deliberately changed. A full diff review with the release notes still in context catches those. Atlas snapshots file changes as git patches, so an upgrade that turns out to be wrong is diffed and rolled back.

## Steps

1. Run the package manager upgrade through bash and capture the full output. If the output exceeds the limits it is saved to a file you can read.
2. Fetch the library's release notes with webfetch so the breaking changes are in context before you start editing.
3. Build or typecheck with bash and let the compiler enumerate the breakage, rather than predicting it.
4. Fix each error with the edit tool, using the lsp tool's goToDefinition operation to inspect the new signatures in the upgraded package.
5. Approve or reject each unified diff Atlas surfaces before the edit is written to disk.
6. Re-run build and tests with bash until clean, checking the release notes for silent behavior changes the compiler never flagged.
7. Review the whole diff before committing, so no fix is merely a suppression of the error rather than a real migration.

## FAQ

### how do I upgrade a major version of a library and fix the errors

Run the package manager upgrade through bash in Atlas, fetch the library's release notes with webfetch, then build or typecheck with bash and let the compiler enumerate the breakage. Fix each error with edit, using the lsp tool's goToDefinition to check the new signatures.

### why should I read the changelog before fixing upgrade errors?

A compiler error says a call no longer typechecks. The changelog says why, and what to do instead. Some breaking changes produce no error at all, such as a default value that flipped, so webfetch pulls the release notes before editing to catch what the compiler cannot see.

### can Atlas figure out what a dependency upgrade will break before running it?

Atlas does not predict the breakage. Atlas builds or typechecks with bash and reads the real compiler output, because the compiler produces the exact failure list for your codebase while any prediction produces a list for a hypothetical one.

### how do I check the new signature of an upgraded package API?

Use the lsp tool's goToDefinition operation. It reads the definition that is actually installed after the upgrade, showing the current parameter list, return type, and overloads. Documentation lags and changelogs summarize, but the installed package is authoritative.

### what happens if the package manager output is too long for Atlas?

Atlas captures the full output of the bash upgrade, and if the output exceeds the limits it is saved to a file you can read. That matters on a major bump, where the resolver's report of transitive dependency changes often explains a failure unrelated to the library you named.

### does Atlas edit my code without showing me during an upgrade?

No. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, and every tool call, including each bash command, is permission-gated against allow, ask, and deny rules before it runs.

### how do I roll back a dependency upgrade Atlas made?

Atlas snapshots file changes as git patches, so edits can be diffed and rolled back. An upgrade whose fixes turn out to be wrong is reverted from the snapshot rather than reconstructed by hand across every file the build errors sent you to.

---

Canonical HTML: https://runatlas.sh/resources/workflows/upgrade-a-dependency-and-fix-the-breakage
Source of truth: aeo_pages row `/resources/workflows/upgrade-a-dependency-and-fix-the-breakage` (segment: Workflows) (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.