microsoft/aspire · error · IOException

Unable to create a unique browser-log command artifact file…

Error message

Unable to create a unique browser-log command artifact file under '{directory}'.

What it means

BrowserLogsArtifacts.WriteArtifactAsync generates candidate file names and creates the artifact file in a command artifacts directory. If it cannot create a unique file there (every candidate name collides or creation fails), it throws this IOException to signal the browser-log artifact could not be persisted.

Solutions

1. Verify the artifacts directory is writable by the process user.
2. Free disk space / check quota.
3. Clean stale artifacts from the directory.
4. Shorten the artifacts directory path or resource names to avoid path-length limits.

Example fix

// before
var artifact = await artifacts.WriteArtifactAsync(resource, BrowserLogsArtifactType.Console, directory: readOnlyDir, content, ct);

// after
Directory.CreateDirectory(directory);
if (!IsWritable(directory)) throw new InvalidOperationException("Configure a writable browser-logs artifacts directory.");
var artifact = await artifacts.WriteArtifactAsync(resource, BrowserLogsArtifactType.Console, directory, content, ct);

// Pre-check the artifacts directory before writing
if (!Directory.Exists(directory)) Directory.CreateDirectory(directory);
var probe = Path.Combine(directory, ".write-test");
using (var fs = File.Create(probe)) { }
File.Delete(probe);

try { artifact = await artifacts.WriteArtifactAsync(resource, type, directory, content, ct); }
catch (IOException ex) { logger.LogError(ex, "Cannot persist browser-log artifact under {Dir}; cleaning stale files.", directory); CleanStaleArtifacts(directory, olderThan: TimeSpan.FromHours(1)); }

When it happens

Trigger: Writing a browser-log artifact when candidate filenames under the target directory are exhausted by collisions, or file creation fails (read-only directory, full disk, path-length limits).

Common situations: Artifacts directory holding thousands of same-named files; running under an account without write permission to the artifacts folder; long AppHost/resource names pushing paths past MAX_PATH on Windows; disk quota exceeded.

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

• The filesystem spelling of
• Browser user data directory
• Bundle version directory
• Could not replace Aspire skills cache directory
• Failed to acquire file lock

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

Appendix: source

Thrown at src/Aspire.Hosting.Browsers/BrowserLogsArtifacts.cs:93

            FileStream stream;
            try
            {
                stream = new FileStream(filePath, FileMode.CreateNew, FileAccess.Write, FileShare.Read, bufferSize: 64 * 1024, useAsync: true);
            }
            catch (IOException) when (attempt < 99 && File.Exists(filePath))
            {
                continue;
            }

            await using (stream.ConfigureAwait(false))
            {
                await stream.WriteAsync(content, cancellationToken).ConfigureAwait(false);
            }

            return new BrowserLogsArtifact(resourceName, artifactType, filePath, mimeType, content.Length, createdAt);
        }

        throw new IOException($"Unable to create a unique browser-log command artifact file under '{directory}'.");
    }

    private static string GetAppHostSegment(string? appHostKey)
    {
        if (string.IsNullOrWhiteSpace(appHostKey))
        {
            return "unknown-apphost";
        }

        var segment = appHostKey.Length > AppHostKeySegmentLength
            ? appHostKey[..AppHostKeySegmentLength]
            : appHostKey;

        return SanitizePathSegment(segment, fallback: "unknown-apphost");
    }

    private static string GetAspireCommandArtifactRoot()
    {

View on GitHub (pinned to 25830f84bd)