microsoft/aspire · error · TimeoutException

Sandbox disk image ' ' was not ready after seconds (last…

Error message

Sandbox disk image '{diskImage.Id}' was not ready after {DiskImageReadyTimeoutSeconds} seconds (last state: '{diskImage.Status.State}').

What it means

Before deploying a sandbox container from a disk image, Aspire polls the image until its status state becomes Ready, waiting up to DiskImageReadyTimeoutSeconds. If the image still is not ready when the timeout elapses, a TimeoutException is thrown reporting the last observed state.

Solutions

Retry the deployment later — image creation is often just slow; the image may complete on its own.
Check the disk image's status/state in Azure to see whether it failed (terminal states are handled separately) or is still progressing.
Increase the wait budget if your images legitimately take longer, or pre-create/warm the image before deployment so it is Ready in advance.

Defensive patterns

Strategy: retry

Try / catch

try { await deployment.DeployAsync(...); }
catch (TimeoutException ex) when (ex.Message.Contains("was not ready after"))
{
    // image build still in progress or hung; check Azure portal state,
    // wait and retry with backoff, or pre-create the image
}

Prevention

Pre-create disk images and wait for Ready before scheduling deployments.
Allow a larger time budget for large images or new regions.
Monitor image build status in Azure to distinguish slow from failed builds.

When it happens

Trigger: Calling the sandbox deployment path that uses a newly created AzureDevComputeDiskImage while the image is stuck in a non-Ready, non-terminal state (e.g. 'Creating'/'Pending') beyond DiskImageReadyTimeoutSeconds, with 2-second polling intervals.

Common situations: Large image builds under way during Azure capacity pressure, slow image replication in a new region, or a hung provisioning operation on the Azure side.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/33ccca1aaac95a65. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxContainerDeployment.cs:718

    {
        var deadline = DateTimeOffset.UtcNow.AddSeconds(DiskImageReadyTimeoutSeconds);
        while (DateTimeOffset.UtcNow < deadline)
        {
            if (IsDiskImageReady(diskImage))
            {
                return diskImage;
            }

            if (IsTerminalDiskImageFailure(diskImage))
            {
                throw CreateDiskImageFailureException(diskImage);
            }

            await Task.Delay(TimeSpan.FromSeconds(2), context.CancellationToken).ConfigureAwait(false);
            diskImage = await client.GetDiskImageAsync(scope, diskImage.Id, context.CancellationToken).ConfigureAwait(false);
        }

        throw new TimeoutException($"Sandbox disk image '{diskImage.Id}' was not ready after {DiskImageReadyTimeoutSeconds} seconds (last state: '{diskImage.Status.State}').");
    }

    private static bool IsDiskImageReady(AzureDevComputeDiskImage diskImage) =>
        string.Equals(diskImage.Status.State, "Ready", StringComparison.OrdinalIgnoreCase);

    private static bool IsTerminalDiskImageFailure(AzureDevComputeDiskImage diskImage) =>
        diskImage.Status.State.Contains("fail", StringComparison.OrdinalIgnoreCase) ||
        diskImage.Status.State.Contains("error", StringComparison.OrdinalIgnoreCase);

    internal static InvalidOperationException CreateDiskImageFailureException(AzureDevComputeDiskImage diskImage)
    {
        ArgumentNullException.ThrowIfNull(diskImage);
        return new InvalidOperationException(
            $"Sandbox disk image '{diskImage.Id}' failed to become ready (terminal state: '{diskImage.Status.State}'). Service-provided error details were redacted.");
    }

    private static Task<AzureDevComputeSandbox> CreateSandboxAsync(
        PipelineStepContext context,

View on GitHub (pinned to 25830f84bd)