microsoft/aspire · critical · InvalidOperationException

Bundle extraction failed. Run 'aspire setup --force' to…

Error message

Bundle extraction failed. Run 'aspire setup --force' to retry, or reinstall the Aspire CLI.

What it means

BundleService extracts the CLI's embedded bundle payload to a local directory before commands run. EnsureExtractedAsync throws InvalidOperationException when the extraction step reports ExtractionFailed, telling the user to run 'aspire setup --force' or reinstall, because the CLI installation is incomplete or corrupted and cannot self-heal in place.

Solutions

Run 'aspire setup --force' to wipe and re-extract the bundle.
Reinstall the Aspire CLI (re-download the install script and rerun it).
Check free disk space and write permissions on the CLI data/extract directory.
Temporarily disable antivirus/security software that may quarantine extracted files, then retry setup.

Example fix

// recovery (shell, not code)
// before: aspire new  -> error: Bundle extraction failed...
// after:
// aspire setup --force
// aspire new

Defensive patterns

Strategy: retry

Try / catch

try { await bundleService.EnsureExtractedAsync(ct); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Bundle extraction failed")) { Console.Error.WriteLine("Run 'aspire setup --force' or reinstall the Aspire CLI."); }

Prevention

Keep adequate free disk space where the CLI extracts bundles
Don't interrupt 'aspire setup' mid-extraction
Exclude the CLI install directory from antivirus quarantine
After upgrading the CLI, run setup once before heavy use

When it happens

Trigger: Calling EnsureExtractedAsync when ExtractAsync returns BundleExtractResult.ExtractionFailed — e.g. disk full, permission denied on the extract directory, corrupted/truncated bundle payload, or antivirus interference.

Common situations: Upgraded CLI left a partially-written extraction directory; read-only or permission-restricted install location; low disk space; corporate security software blocking extraction of executable payloads.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Bundles/BundleService.cs:95

    internal static readonly string[] s_linkedLayoutDirectories = [
        BundleDiscovery.BundleDirectoryName,
    ];

    /// <inheritdoc/>
    public async Task EnsureExtractedAsync(CancellationToken cancellationToken = default)
    {
        var extractDir = GetBundleExtractDirForCurrentProcess();
        if (string.IsNullOrEmpty(extractDir))
        {
            return;
        }

        logger.LogDebug("Ensuring bundle is extracted to {ExtractDir}.", extractDir);
        var result = await ExtractAsync(extractDir, force: false, cancellationToken);

        if (result is BundleExtractResult.ExtractionFailed)
        {
            throw new InvalidOperationException(
                "Bundle extraction failed. Run 'aspire setup --force' to retry, or reinstall the Aspire CLI.");
        }
    }

    /// <inheritdoc/>
    public async Task<BundleLayoutLease?> EnsureExtractedAndAcquireLayoutAsync(string holderKind, string? commandName = null, CancellationToken cancellationToken = default)
    {
        var extractDir = GetBundleExtractDirForCurrentProcess();
        if (string.IsNullOrEmpty(extractDir))
        {
            var fallbackLayout = layoutDiscovery.DiscoverLayout();
            return fallbackLayout is null
                ? null
                : new BundleLayoutLease(fallbackLayout, lease: null);
        }

        var lockPath = Path.Combine(extractDir, ".aspire-bundle-lock");
        using var fileLock = await FileLock.AcquireAsync(lockPath, cancellationToken).ConfigureAwait(false);

View on GitHub (pinned to 25830f84bd)