// Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions.
| name | dart-resolve-package-conflicts |
| description | Workflow for fixing package version conflicts. Use this when `pub get` fails due to incompatible package versions. |
| metadata | {"model":"models/gemini-3.1-pro-preview","last_modified":"Fri, 24 Apr 2026 15:11:14 GMT"} |
Dart enforces a strict single-version rule for dependencies: a project and all its transitive dependencies must resolve to a single, shared version of any given package. This prevents runtime type mismatches but introduces the risk of "version lock."
To mitigate version lock, Dart relies on version constraints rather than pinned versions in the pubspec.yaml. The pubspec.lock file maintains the exact resolved versions for reproducible builds.
Understand the output columns of dart pub outdated:
pubspec.lock.pubspec.yaml. dart pub upgrade resolves to this.^1.2.3) for dependencies in pubspec.yaml. This allows pub to select newer, non-breaking versions (up to, but not including, the next major version) during resolution.dev_dependencies to the exact version currently used. This reduces resolution complexity and prevents older, incompatible dev tools from being selected.dart pub get --enforce-lockfile in CI/CD pipelines to ensure the exact versions tested locally are used in production.Run this workflow periodically to identify stale packages that may impact stability or performance.
Task Progress:
dart pub outdated.pubspec.yaml.pubspec.yaml to update.Use conditional logic based on the audit results to upgrade dependencies.
Task Progress:
dart pub upgrade.dart pub upgrade --tighten to automatically update the lower bounds in pubspec.yaml to match the newly resolved versions.pubspec.yaml to bump the version constraint to match the "Resolvable" column (e.g., change ^0.11.0 to ^0.12.1).dart pub upgrade to resolve the new constraints and update pubspec.lock.dart analyze -> review errors -> fix breaking API changes.dart test -> review failures -> fix regressions.When pub cannot find a set of concrete versions that satisfy all constraints, or when dealing with a retracted package version, manipulate the lockfile surgically.
NEVER delete the entire pubspec.lock file and run dart pub get. This causes uncontrolled upgrades across the entire dependency graph.
Task Progress:
pubspec.lock.dart pub get to fetch the newest compatible, non-retracted version for that specific package.dart pub deps -> verify the dependency graph resolves correctly.pubspec.yaml, and retry.When dart pub outdated shows a package is resolvable to a higher minor/patch version, use the --tighten flag to update the pubspec.yaml automatically.
Input (pubspec.yaml):
dependencies:
http: ^0.13.0
Command:
dart pub upgrade --tighten http
Output (pubspec.yaml):
dependencies:
http: ^0.13.5
If package_a is retracted or locked in a conflict, remove only its block from pubspec.lock.
Before (pubspec.lock):
packages:
package_a:
dependency: "direct main"
description:
name: package_a
url: "https://pub.dev"
source: hosted
version: "1.0.0" # Retracted version
package_b:
dependency: "direct main"
# ...
Action: Delete the package_a block entirely. Leave package_b untouched. Run dart pub get.
Replace the usage of `expect` and similar functions from `package:matcher` to `package:checks` equivalents.
Write and organize unit tests for functions, methods, and classes using `package:test`. Use when creating new logic or fixing bugs to ensure code remains correct and regression-free.
Entrypoint structure, exit codes, cross-platform scripts. Use when building command line utilities, scripts, or applications.
Collect coverage using the coverage packge and create an LCOV report
Uses get_runtime_errors and lsp to fetch an active stack trace, locate the failing line, apply a fix, and verify resolution via hot_reload.
Define and generate mock objects for external dependencies using `package:mockito` and `build_runner`. Use when unit testing classes that depend on complex external services like APIs or databases.