microsoft/aspire · error · UnauthorizedAccessException

Cannot write to installation directory

Error message

Cannot write to installation directory '{0}'. Please run the update with elevated permissions (e.g., using sudo on Linux/macOS).

What it means

During archive self-update, file operations into the CLI's installation directory (backup, replace) may raise UnauthorizedAccessException when the process lacks write permission. The command wraps it and rethrows with a clearer message including the install directory and the elevation hint (sudo on Linux/macOS).

Solutions

Re-run the update with elevated permissions: `sudo aspire update --self` (Linux/macOS) or an elevated shell on Windows
Change ownership/permissions of the install directory so your user can write it
Reinstall the CLI into a user-writable location (e.g. ~/.aspire/bin) with the installer script
On Windows, take ownership of the install directory or use an admin terminal

Example fix

// before
aspire update --self
// after
sudo aspire update --self

Defensive patterns

Strategy: validation

Validate before calling

var installDir = Path.GetDirectoryName(Environment.ProcessPath)!;
if (!HasWriteAccess(installDir))
    Console.Error.WriteLine("No write access to install dir; run with sudo or an elevated shell.");

Try / catch

try { await UpdateSelfAsync(); }
catch (UnauthorizedAccessException ex) { Console.Error.WriteLine($"Permission denied: {ex.Message}"); return 1; }

Prevention

Install the CLI to a user-writable location if you update frequently without sudo
Pair sudo usage with -E or correct ownership so the update can run elevated
Check directory ACLs/ownership before scripted updates

When it happens

Trigger: `aspire update --self` when the CLI was installed to a root-owned location such as /usr/local/bin on Linux/macOS, or a protected Program Files directory on Windows, and the update is run without elevated privileges.

Common situations: System-wide installs performed with sudo but later updated from a normal user shell; CI containers running as non-root with the binary owned by root.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Commands/UpdateCommand.cs:869

            }
            catch
            {
                // If anything goes wrong, restore the backup
                _logger.LogWarning("Update failed, restoring backup");
                if (backupPath is not null && File.Exists(backupPath))
                {
                    if (File.Exists(targetExePath))
                    {
                        File.Delete(targetExePath);
                    }
                    File.Move(backupPath, targetExePath);
                }
                throw;
            }
        }
        catch (UnauthorizedAccessException)
        {
            throw new UnauthorizedAccessException(
                string.Format(CultureInfo.CurrentCulture, UpdateCommandStrings.NoWritePermissionToInstallDirectory, installDir));
        }
        finally
        {
            // Clean up temp directories
            CleanupDirectory(tempExtractDir);
            CleanupDirectory(Path.GetDirectoryName(archivePath)!);
        }
    }

    private static bool IsInPath(string directory, IEnvironment environment)
    {
        var pathEnv = Environment.GetEnvironmentVariable("PATH");
        if (string.IsNullOrEmpty(pathEnv))
        {
            return false;
        }

View on GitHub (pinned to 25830f84bd)