First decide whether the failure comes from the upgrade or from something else. Rerun once to rule out a flaky test, then read the failure, then choose: fix the code, adjust the change, defer with a recorded reason, or close. Do not merge over a red check without a written reason.
Step 1: classify the failure
| Symptom | Likely cause | Next move |
|---|---|---|
| Passes on rerun | Flaky test | Log the test, merge if now green |
| Fails on files the PR did not touch | Pre-existing failure on the base branch | Fix main first |
| Fails in code that calls the package | Real API change | Go to step 2 |
| Fails at install or build | Peer dependency or resolution conflict | Check the lockfile and constraints |
| Fails on a new vulnerability or policy gate | The new version has its own finding | Pick a different fixed version |
The classification takes minutes and prevents most wasted effort.
Step 2: read what changed
Look at the release notes and the version jump. A major version bump, or a 0.y.z package, promises little: semver.org says major version zero is for initial development where anything may change. See how risky a patch, minor or major fix is.
Step 3: choose a path
- Fix forward. Small code adjustments in the same branch, then rerun. Good when the change is clear and local.
- Pick a different version. A lower fixed version, or a backport, may avoid the break. Check fixed version or backported fix.
- Defer with a reason. If the vulnerability is not reachable or has a mitigation, record that and set a date to revisit. See when to close a fix PR without merging.
- Close. If the fix is not applicable, close it with a note so the bot does not reopen the same debate.
Keep the evidence
A failed fix attempt is useful data for the next one and for audits. Record the failure class, the decision and the owner. Over time, repeated failures in one dependency suggest putting it on a manual-only list.
What never to do
Never merge a red fix PR because the vulnerability sounds scary. If the risk is high enough to justify an exception, document it and use the exception register, rather than bypassing the checks quietly.
Example: a build fails after a patch bump
Imagine a patch bump of an HTTP client fails a test that checks an error message. The notes show the maintainer reworded the message. The code is fine, the test was brittle. Update the assertion to check the error type, rerun, and merge, noting the change in the pull request. Contrast that with a failure in a serialisation test, where output differs. That deserves a closer look before anything merges.
Where Safeguard fits
Safeguard's autonomous remediation opens fix pull requests on Manual approval by default, and gates can require passing checks before a merge. Run a free scan to see current findings.
Quick check
How many reruns are reasonable?
One. If it fails twice, treat it as a real failure and investigate.
Should the bot retry automatically?
A single automatic retry is fine. Repeated retries hide flaky tests.
Sources
Last reviewed: 19 October 2026.
