Fix: Skip container runtime check for Archive destinations and improve error messages #13576

Copilot · 2025-12-15T22:58:06Z

Description

When using aspire deploy with Azure Container Apps, deployment fails with cryptic error "CONTAINER1012: The local registry is not available" if Docker isn't running, even when images are configured to save as archives rather than push to registries.

Changes

ResourceContainerImageManager.cs

BuildImageAsync: Moved container runtime health check to beginning of method, applying to all resource types (not just Dockerfile builds)
ResolvedContainerBuildOptions: Added Destination property to track the container image destination
ResolveContainerBuildOptionsAsync: Now sets Destination property from the callback context
ResourcesRequireContainerRuntimeAsync:
- Skip runtime check for resources with ContainerImageDestination.Archive set
- Check Destination directly from ResolvedContainerBuildOptions to avoid redundant callback invocations
- Optimized to call ResolveContainerBuildOptionsAsync once per resource
Error Messages: Updated error logs and exception messages to include container runtime name (e.g., "Container runtime 'docker' is not running") for improved diagnostics
Preserve existing logic: OCI format + OutputPath combination doesn't require Docker

Test Infrastructure

FakeContainerRuntime: Add isRunning parameter and CheckIfRunningCallCount tracking
New tests validate runtime checks are skipped/required appropriately for Archive/Registry/Dockerfile scenarios
Updated test assertions to match new error message format with container runtime name

Example

// Archive destination - no Docker required
var project = builder.AddProject<Projects.Api>("api")
    .WithContainerBuildOptions(ctx =>
    {
        ctx.Destination = ContainerImageDestination.Archive;
        ctx.OutputPath = "/tmp/archives";
    });

// Dockerfile - Docker always required
var container = builder.AddDockerfile("myapp", "./context", "./Dockerfile");

Checklist

Is this feature complete?
- Yes. Ready to ship.
- No. Follow-up changes expected.
Are you including unit tests for the changes and scenario tests if relevant?
- Yes
- No
Did you add public API?
- Yes
- No
Does the change make any security assumptions or guarantees?
- Yes
- No
Does the change require an update in our Aspire docs?
- Yes
- No

Original prompt

This section details on the original issue you should resolve

<issue_title>aspire deploy required docker to rung when using AddAzureContainerAppEnvironment</issue_title>
<issue_description>### Is there an existing issue for this?

I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

aspire deploy on the PostgresEndToEnd playground app without docker running fails without any information.
17:10:21 (build-api) ✗ [ERR] Step 'build-api' failed.
17:10:21 (build-api) ✗ Step 'build-api' failed: Command dotnet publish "D:\aspire\playground\PostgresEndToEnd\PostgresEndToEnd.ApiService\PostgresEndToEnd.ApiService.csproj" --configuration Release /t:PublishContainer /p:ContainerRepository="api" /p:ContainerRuntimeIdentifier="linux-x64" returned non-zero exit code 1
17:10:21 (create-provisioning-context) ✗ [ERR] Step 'create-provisioning-context' failed.
17:10:21 (create-provisioning-context) ✗ Step 'create-provisioning-context' failed: The operation was canceled.
17:10:21 (pipeline execution) ✗ [ERR] Multiple pipeline steps failed: create-provisioning-context, build-api (Step 'create-provisioning-context' failed: The operation was canceled.) (Step 'build-api' failed: Command dotnet publish "D:\aspire\playground\PostgresEndToEnd\PostgresEndToEnd.ApiService\PostgresEndToEnd.ApiService.csproj" --configuration Release /t:PublishContainer /p:ContainerRepository="api" /p:ContainerRuntimeIdentifier="linux-x64" returned non-zero exit code 1)
17:10:21 (pipeline execution) ✗ Failed
With the debug log I get:
error CONTAINER1012: The local registry is not available, but pushing to a local registry was requested.
Describe the solution you'd like

These errors go away when Docker is running. I think there should be a better error message if this is known to be required.

Additional context

No response</issue_description>

<agent_instructions>Update ResourcesRequireContainerRuntimeAsync to check if the ContainerImageDestination is Archive and skip the runtime check if so. Add the runtime check to BuildImageAsync as well.</agent_instructions>

Comments on the Issue (you are @copilot in this section)
@sebastienros This is not similar to https://github.com//issues/11408 which states we should try to not require Docker. What's interesting is that this issue actually shows that Docker is required, so it's not displayed anymore in the new pipeline deploy.

Fixes aspire deploy required docker to rung when using AddAzureContainerAppEnvironment #13045

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

- Updated ResourcesRequireContainerRuntimeAsync to skip runtime check for resources with Archive destination - Added runtime check to BuildImageAsync for Dockerfile resources - Updated FakeContainerRuntime test helper to support isRunning parameter - Added tests to verify the behavior (3 of 4 passing, 1 test needs refinement) Co-authored-by: captainsafia <[email protected]>

…ibility Reordered logic to check Dockerfile resources first, then Archive destination, preserving the original behavior for OCI + OutputPath combinations. Co-authored-by: captainsafia <[email protected]>

src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs

- Move container runtime check to beginning of BuildImageAsync for all resource types - Optimize ResourcesRequireContainerRuntimeAsync to call ResolveContainerBuildOptionsAsync once - Only check Destination when OutputPath is present to avoid unnecessary callback Co-authored-by: captainsafia <[email protected]>

captainsafia · 2025-12-15T23:30:48Z

src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs

+            // Skip resources that are explicitly configured to save as archives - they don't need Docker
+            if (options.OutputPath is not null)
+            {
+                var buildOptionsContext = await resource.ProcessContainerBuildOptionsCallbackAsync(


@copilot Don't recompute buildOptionsContext here. Add Destination to ResolvedContainerBuildOptions and update ResolveContainerBuildOptionsAsync to set it. Then check for the value directly on the ResolvedContainerBuildOptions options object here.

Done in commit 82bdd4b. Added Destination property to ResolvedContainerBuildOptions, set it in ResolveContainerBuildOptionsAsync, and now checking it directly in ResourcesRequireContainerRuntimeAsync without recomputing buildOptionsContext.

- Added Destination property to ResolvedContainerBuildOptions class - Set Destination in ResolveContainerBuildOptionsAsync from context - Use Destination directly in ResourcesRequireContainerRuntimeAsync instead of calling ProcessContainerBuildOptionsCallbackAsync again - Simplifies logic and avoids redundant callback invocations Co-authored-by: captainsafia <[email protected]>

github-actions · 2025-12-15T23:40:10Z

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 13576

Or

Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 13576"

captainsafia · 2025-12-15T23:53:34Z

src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs

+
+            if (!containerRuntimeHealthy)
+            {
+                logger.LogError("Container runtime is not running or is unhealthy. Cannot build container image.");


@copilot

Suggested change

logger.LogError("Container runtime is not running or is unhealthy. Cannot build container image.");

logger.LogError("Container runtime '{ContainerRuntimeName}' is not running or is unhealthy. Cannot build container image.", ContainerRuntime.Name);

Include the container runtime name here and in the exception below.

Done in commit e25852e. Updated both the log error message and exception message to include the container runtime name. Also updated test assertions to work with the new format.

- Updated error log and exception messages to include container runtime name - Changed from "Container runtime is not running" to "Container runtime '{name}' is not running" - Updated test assertions to match new error message format - Improves error diagnostics by showing which runtime (docker/podman) is being checked Co-authored-by: captainsafia <[email protected]>

Copilot

Pull request overview

This PR fixes an issue where aspire deploy fails with a cryptic error message when Docker isn't running, even when container images are configured to save as archives (which don't require Docker). The changes improve error messages by including the container runtime name and optimize the runtime check logic to skip validation for Archive destinations.

Key Changes

Added logic to skip container runtime checks for resources with ContainerImageDestination.Archive
Improved error messages to include the specific container runtime name (e.g., "Container runtime 'docker' is not running")
Added runtime health check to BuildImageAsync method to catch issues earlier for individual resource builds

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs	Added `Destination` property to `ResolvedContainerBuildOptions`, updated `ResourcesRequireContainerRuntimeAsync` to skip runtime checks for Archive destinations, improved error messages with runtime name, and added runtime check to `BuildImageAsync`
tests/Aspire.Hosting.Tests/Publishing/FakeContainerRuntime.cs	Added `isRunning` parameter and `CheckIfRunningCallCount` tracking to support testing runtime check scenarios
tests/Aspire.Hosting.Tests/Publishing/ResourceContainerImageManagerTests.cs	Added comprehensive test coverage for Archive/Registry/Dockerfile scenarios, mixed destinations, and updated existing test assertions to match new error message format

Copilot · 2025-12-16T00:19:25Z

src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs

        var options = await ResolveContainerBuildOptionsAsync(resource, cancellationToken).ConfigureAwait(false);

+        // Check if this resource needs a container runtime
+        if (await ResourcesRequireContainerRuntimeAsync([resource], cancellationToken).ConfigureAwait(false))


The ResolveContainerBuildOptionsAsync method is being called twice in BuildImageAsync - once at line 239 and again inside ResourcesRequireContainerRuntimeAsync at line 531. This is inefficient since the options are already resolved and available. Consider passing the already-resolved options to ResourcesRequireContainerRuntimeAsync to avoid redundant callback invocations, or move the runtime check before the options resolution to avoid the duplicate work.

captainsafia · 2025-12-16T00:26:45Z

/backport to release/13.1

github-actions · 2025-12-16T00:26:53Z

Started backporting to release/13.1: https://github.com/dotnet/aspire/actions/runs/20252173091

Initial plan

e016b73

Copilot AI assigned Copilot and captainsafia Dec 15, 2025

Copilot started work on behalf of captainsafia December 15, 2025 22:58 View session

Copilot AI and others added 2 commits December 15, 2025 23:10

Fix ResourcesRequireContainerRuntimeAsync to maintain backward compat…

664f15c

…ibility Reordered logic to check Dockerfile resources first, then Archive destination, preserving the original behavior for OCI + OutputPath combinations. Co-authored-by: captainsafia <[email protected]>

Copilot AI changed the title ~~[WIP] Fix aspire deploy failure when docker is not running~~ Fix: Skip container runtime check for Archive destinations in aspire deploy Dec 15, 2025

Copilot AI requested a review from captainsafia December 15, 2025 23:16

Copilot finished work on behalf of captainsafia December 15, 2025 23:16

captainsafia reviewed Dec 15, 2025

View reviewed changes

src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs Outdated Show resolved Hide resolved

src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs Outdated Show resolved Hide resolved

Copilot started work on behalf of captainsafia December 15, 2025 23:19 View session

Copilot AI requested a review from captainsafia December 15, 2025 23:26

Copilot finished work on behalf of captainsafia December 15, 2025 23:26

captainsafia reviewed Dec 15, 2025

View reviewed changes

Copilot started work on behalf of captainsafia December 15, 2025 23:31 View session

Copilot AI requested a review from captainsafia December 15, 2025 23:37

Copilot finished work on behalf of captainsafia December 15, 2025 23:37

captainsafia reviewed Dec 15, 2025

View reviewed changes

Copilot started work on behalf of captainsafia December 15, 2025 23:54 View session

Copilot AI changed the title ~~Fix: Skip container runtime check for Archive destinations in aspire deploy~~ Fix: Skip container runtime check for Archive destinations and improve error messages Dec 16, 2025

Copilot finished work on behalf of captainsafia December 16, 2025 00:03

Copilot AI requested a review from captainsafia December 16, 2025 00:03

captainsafia marked this pull request as ready for review December 16, 2025 00:09

captainsafia requested a review from mitchdenny as a code owner December 16, 2025 00:09

Copilot AI review requested due to automatic review settings December 16, 2025 00:09

Copilot started reviewing on behalf of captainsafia December 16, 2025 00:10 View session

mitchdenny approved these changes Dec 16, 2025

View reviewed changes

Copilot AI reviewed Dec 16, 2025

View reviewed changes

captainsafia enabled auto-merge (squash) December 16, 2025 00:20

captainsafia merged commit 57f91f8 into main Dec 16, 2025
294 of 298 checks passed

captainsafia deleted the copilot/fix-aspire-deploy-docker-issue branch December 16, 2025 00:26

dotnet-policy-service bot added this to the 13.2 milestone Dec 16, 2025

github-actions bot mentioned this pull request Dec 16, 2025

[release/13.1] Fix: Execute container runtime health check on single-image builds #13579

Merged

Copilot AI mentioned this pull request Dec 16, 2025

[release/13.1] Fix: Skip container runtime check for Archive destinations and improve error messages #13580

Merged

10 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Fix: Skip container runtime check for Archive destinations and improve error messages #13576

Fix: Skip container runtime check for Archive destinations and improve error messages #13576

Copilot AI commented Dec 15, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

captainsafia Dec 15, 2025

Uh oh!

Copilot AI Dec 15, 2025

Uh oh!

github-actions bot commented Dec 15, 2025 •

edited

Loading

Uh oh!

captainsafia Dec 15, 2025

Uh oh!

Copilot AI Dec 16, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 16, 2025

Uh oh!

Uh oh!

captainsafia commented Dec 16, 2025

Uh oh!

github-actions bot commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	logger.LogError("Container runtime is not running or is unhealthy. Cannot build container image.");
	logger.LogError("Container runtime '{ContainerRuntimeName}' is not running or is unhealthy. Cannot build container image.", ContainerRuntime.Name);

Fix: Skip container runtime check for Archive destinations and improve error messages #13576

Fix: Skip container runtime check for Archive destinations and improve error messages #13576

Conversation

Copilot AI commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Example

Checklist

Is your feature request related to a problem? Please describe the problem.

Describe the solution you'd like

Additional context

Comments on the Issue (you are @copilot in this section)

Uh oh!

Uh oh!

Uh oh!

captainsafia Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

captainsafia Dec 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Copilot AI Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

captainsafia commented Dec 16, 2025

Uh oh!

github-actions bot commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Dec 15, 2025 •

edited

Loading

github-actions bot commented Dec 15, 2025 •

edited

Loading