Unity-Technologies/UnityCsReference · error · IOException

FileUtil.OpenRead: Failed to acquire UDS content for '{path}

Error message

FileUtil.OpenRead: Failed to acquire UDS content for '{path}'

What it means

After parsing the UDS hash, OpenReadUDS calls UDS.Acquire(hash); a zero IntPtr return means the native store could not resolve/lock the content for that hash, and the method throws IOException. Acquire can fail when the content was evicted from the local cache, the GUID/hash is stale, the underlying artefact was deleted, or the store is temporarily unavailable.

Source

Thrown at Editor/Mono/FileUtil.cs:55

            // The 'physical' path for a VirtualArtifact will be a UDS virtual path
            if (physicalPath.StartsWith(k_UdsPathPrefix, StringComparison.Ordinal))
                return OpenReadUDS(physicalPath);

            // Fall back to opening the physical file in the normal way
            return File.Open(physicalPath, FileMode.Open, FileAccess.Read, FileShare.Read);
        }

        static Stream OpenReadUDS(string path)
        {
            string hashStr = path[(path.LastIndexOf('/') + 1)..];
            var hash = Hash128.Parse(hashStr);
            if (!hash.isValid)
                throw new IOException($"FileUtil.OpenRead: Invalid UDS hash in path '{path}'");

            IntPtr handle = UDS.Acquire(hash);
            if (handle == IntPtr.Zero)
                throw new IOException($"FileUtil.OpenRead: Failed to acquire UDS content for '{path}'");

            return new UDSReadStream(handle);
        }

        public static byte[] ReadAllBytes(string path)
        {
            if (string.IsNullOrEmpty(path))
                throw new ArgumentException("Path cannot be null or empty.", nameof(path));

            return ReadAllBytesInternal(path);
        }

        public static string ReadAllText(string path)
        {
            if (string.IsNullOrEmpty(path))
                throw new ArgumentException("Path cannot be null or empty.", nameof(path));

            return ReadAllTextInternal(path);

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Refresh or rebuild the UDS cache (re-import the asset) before retrying.
2. Catch IOException and treat as a cache miss — re-request the content from its authoritative source.
3. Do not hold UDS hash references across long lifetimes without verifying the content still exists.
4. In tests, only use hashes obtained from an actual UDS write, never synthetic ones.

Example fix

// before
using Stream s = FileUtil.OpenRead(udsPath);
// after
try { using Stream s = FileUtil.OpenRead(udsPath); /* read */ }
catch (IOException ex) when (ex.Message.Contains("acquire UDS")) { ReimportAssetFor(udsPath); /* retry */ }

// Best-effort pre-check: confirm the hash resolves before opening.
if (UDS.Acquire(hash) == IntPtr.Zero)
    throw new IOException("UDS content not currently available; re-import and retry.");

try { using Stream s = FileUtil.OpenRead(udsPath); /* read */ }
catch (IOException ex) when (ex.Message.Contains("acquire UDS"))
{ ReimportAssetFor(udsPath); /* then retry once */ }

When it happens

Trigger: Asking for UDS content by a hash that is no longer present (evicted/garbage-collected). Concurrent access where the content is being written. Corrupted local UDS cache. A hash that parsed as valid but does not correspond to stored data.

Common situations: Long-running editor sessions referencing UDS content that was purged. CI machines with a cold/expired cache. Tests that fabricate plausible-but-nonexistent hashes. Race between artefact deletion and a reader.

Related errors

• Failed to Copy File / Directory from '{0}' to '{1}': destina
• Failed to Copy File / Directory from '{0}' to '{1}'.
• Failed to Move File / Directory from '{0}' to '{1}'.
• Failed to delete directory '{0}'.
• FileUtil.OpenRead: Invalid UDS hash in path '{path}'

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/468e484a4c353470. Report an issue: GitHub.