{"record":{"id":"ad6e8619a5bbdc95","repo":"microsoft/aspire","slug":"bundle-extraction-failed-run-aspire-setup-force-to-retry-or","errorCode":null,"errorMessage":"Bundle extraction failed. Run 'aspire setup --force' to retry, or reinstall the Aspire CLI.","messagePattern":"Bundle extraction failed\\. Run 'aspire setup --force' to retry, or reinstall the Aspire CLI\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"src/Aspire.Cli/Bundles/BundleService.cs","lineNumber":95,"sourceCode":"    internal static readonly string[] s_linkedLayoutDirectories = [\n        BundleDiscovery.BundleDirectoryName,\n    ];\n\n    /// <inheritdoc/>\n    public async Task EnsureExtractedAsync(CancellationToken cancellationToken = default)\n    {\n        var extractDir = GetBundleExtractDirForCurrentProcess();\n        if (string.IsNullOrEmpty(extractDir))\n        {\n            return;\n        }\n\n        logger.LogDebug(\"Ensuring bundle is extracted to {ExtractDir}.\", extractDir);\n        var result = await ExtractAsync(extractDir, force: false, cancellationToken);\n\n        if (result is BundleExtractResult.ExtractionFailed)\n        {\n            throw new InvalidOperationException(\n                \"Bundle extraction failed. Run 'aspire setup --force' to retry, or reinstall the Aspire CLI.\");\n        }\n    }\n\n    /// <inheritdoc/>\n    public async Task<BundleLayoutLease?> EnsureExtractedAndAcquireLayoutAsync(string holderKind, string? commandName = null, CancellationToken cancellationToken = default)\n    {\n        var extractDir = GetBundleExtractDirForCurrentProcess();\n        if (string.IsNullOrEmpty(extractDir))\n        {\n            var fallbackLayout = layoutDiscovery.DiscoverLayout();\n            return fallbackLayout is null\n                ? null\n                : new BundleLayoutLease(fallbackLayout, lease: null);\n        }\n\n        var lockPath = Path.Combine(extractDir, \".aspire-bundle-lock\");\n        using var fileLock = await FileLock.AcquireAsync(lockPath, cancellationToken).ConfigureAwait(false);","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Cli/Bundles/BundleService.cs#L77-L113","documentation":"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.","triggerScenarios":"Calling EnsureExtractedAsync when ExtractAsync returns BundleExtractResult.ExtractionFailed — e.g. disk full, permission denied on the extract directory, corrupted/truncated bundle payload, or antivirus interference.","commonSituations":"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.","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."],"exampleFix":"// recovery (shell, not code)\n// before: aspire new  -> error: Bundle extraction failed...\n// after:\n// aspire setup --force\n// aspire new","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await bundleService.EnsureExtractedAsync(ct); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Bundle extraction failed\")) { Console.Error.WriteLine(\"Run 'aspire setup --force' or reinstall the Aspire CLI.\"); }","preventionTips":["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"],"tags":["cli","setup","installation","extraction"],"backgroundTag":"file-write-failed","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}