A pinned local .NET tool fails on a CI agent that only has the .NET 10 runtime; how do dotnet tool update and --allow-roll-forward help?
answer
- framework-dependent tools need their runtime
- --allow-roll-forward on install, run, exec
- manifest entry "rollForward": true
- dotnet tool update --version, --allow-downgrade
- RollForward set by the tool author
basics
~20 sA framework-dependent tool needs the runtime it targets; either update the manifest to a tool version built for .NET 10 with dotnet tool update, or install it with --allow-roll-forward so the manifest records rollForward: true and the tool runs on the newer runtime.
solid answer
~40 sA local tool is usually framework-dependent, so a tool built for `net8.0` will not start on an agent that has only the .NET 10 runtime unless its author allowed roll-forward. Three fixes: install the older runtime on the agent; move to a tool version that targets .NET 10 with `dotnet tool update <id> --version <v>`, which rewrites the manifest entry for review; or let it roll forward with `dotnet tool install <id> --allow-roll-forward`, which writes `"rollForward": true` into the manifest entry so every `dotnet tool run` starts it on a newer runtime. `dotnet tool run --allow-roll-forward` and `dotnet tool exec --allow-roll-forward` do the same for one invocation. Roll-forward across a major version can surface behaviour changes, so prefer a tool version built for your runtime when one exists.
code
bash · 8 lines# Preferred: move the pin to a version built for the current runtime
dotnet tool update dotnet-ef --version 10.0.12
# Stopgap: record rollForward: true in the manifest entry
dotnet tool install "$FORMATTER_ID" --allow-roll-forward
# One invocation only, manifest unchanged
dotnet tool run "$FORMATTER_CMD" --allow-roll-forwardgo deeper
Recall that a tool needs the .NET runtime it was built for, and that dotnet tool update changes the pinned version.
Explain why the SDK and the runtime a tool needs differ, how --allow-roll-forward is recorded in the manifest, and the run and exec variants.
Diagnose the CI failure, prefer a tool version built for the current runtime, use roll-forward as a tracked stopgap, and keep every change in the reviewed manifest.
Plan runtime upgrades across repositories with tool dependencies in mind: inventory pinned tools and their target runtimes before moving CI images to a new major version.
## Why the tool will not start Most .NET tools are **framework-dependent**: the package holds IL and a `runtimeconfig.json` that names the runtime the tool was built for. By default the host rolls forward to newer **patch** and **minor** versions of that runtime, but not to a newer **major** version. A tool built for `net8.0` therefore fails on a CI image that has only the .NET 10 runtime, even though the .NET 10 SDK installed and restored it without complaint. The SDK and the runtime a tool needs are separate things. The team repository in this scenario pins the EF Core tool and a code formatter in `.config/dotnet-tools.json`. The CI image was upgraded to the .NET 10 SDK only, and the formatter step now fails while the EF Core step works. ## Why one tool works and the other does not A tool author can set `<RollForward>Major</RollForward>` in the tool's project. The EF Core tool's project does exactly that, so `dotnet-ef` starts on newer major runtimes. A tool without that setting needs its own major version installed. ## Fix 1: update the pinned version If a newer version of the tool targets .NET 10, update the manifest: 1. `dotnet tool update <id> --version <new>` rewrites the entry in the first manifest that lists the package and installs it. 2. `dotnet tool update --all` updates every tool in scope at once. 3. `--allow-downgrade` lets `install` or `update` move to an **older** version when a new release misbehaves. 4. Commit the manifest change; CI picks it up with `dotnet tool restore`. This is the cleanest fix: the tool runs on the runtime it was built for, and the change is reviewed like any other dependency bump. ## Fix 2: allow roll-forward If no newer tool version exists, let the tool run on the newer runtime: - `dotnet tool install <id> --allow-roll-forward` (available since the .NET 9 SDK) records `"rollForward": true` in the tool's manifest entry. Every later `dotnet tool run` or `dotnet <command>` starts the tool allowing roll-forward. - `dotnet tool run <command> --allow-roll-forward` applies it to one invocation without changing the manifest. - `dotnet tool exec <id> --allow-roll-forward` does the same for one-shot execution. - For global tools, `dotnet tool install -g <id> --allow-roll-forward` applies it to that install. Rolling a tool forward across a major version runs it on a runtime it was never tested against. Usually that works; occasionally a breaking change in the newer runtime shows up as a tool bug. Treat it as a stopgap and track the tool's upstream for a proper release. ## Fix 3: install the runtime Installing the older runtime on the agent alongside the SDK keeps the tool on its tested runtime. It costs image size and one more runtime to patch, and it hides the problem from developers whose machines already have that runtime. ## Choosing | Option | Reviewed in source control | Runtime the tool runs on | Typical use | |---|---|---|---| | `dotnet tool update` to a newer version | yes, manifest diff | the one it targets | a supported release exists | | `--allow-roll-forward` on install | yes, `rollForward` in manifest | newer installed runtime | no release yet | | `--allow-roll-forward` on run or exec | no, pipeline script only | newer installed runtime | a single CI step | | extra runtime on the agent | no, image definition | the one it targets | tools you cannot change |
- Does the .NET 10 SDK on the agent not count as having the runtime?An SDK installation brings the runtimes of its own version, here .NET 10. A tool built for .NET 8 needs a .NET 8 runtime, which the .NET 10 SDK does not include, unless the tool is allowed to roll forward to .NET 10.
- Which manifest does dotnet tool update change when several are in scope?It searches upward from the current directory for the first manifest that already lists the package and updates that entry; if none lists it, it adds the tool to the closest manifest.
- Restoring a tool with the .NET 10 SDK makes it run on .NET 10 automatically.
- A framework-dependent tool rolls forward to a new major runtime by default.
- dotnet tool restore upgrades tools whose target runtime is missing.
- --allow-roll-forward only works for global tools.
- dotnet tool update can only move a tool to a newer version.