Unity-Technologies/UnityCsReference · error · IOException

Failed to Copy File / Directory from '{0}' to '{1}'.

Error message

Failed to Copy File / Directory from '{0}' to '{1}'.

What it means

After the destination-exists check passes, CopyFileOrDirectory invokes the native CopyFileOrDirectoryInternal; if it returns false the method throws System.IO.IOException with the generic 'Failed to Copy' message. A false return from the native side signals a low-level OS error (permissions, locked file, missing source, path-too-long, I/O fault) that the managed layer does not classify further.

Source

Thrown at Editor/Mono/FileUtil.bindings.cs:47

        private static extern bool DeleteFileOrDirectoryInternal(string path);

        [FreeFunction("IsPathCreated")]
        private static extern bool PathExists(string path);

        // Copies a file or directory.
        public static void CopyFileOrDirectory(string source, string dest)
        {
            CheckForValidSourceAndDestinationArgumentsAndRaiseAnExceptionWhenNullOrEmpty(source, dest);

            if (PathExists(dest))
            {
                throw new System.IO.IOException(string.Format(
                    "Failed to Copy File / Directory from '{0}' to '{1}': destination path already exists.", source, dest));
            }

            if (!CopyFileOrDirectoryInternal(source, dest))
            {
                throw new System.IO.IOException(string.Format(
                    "Failed to Copy File / Directory from '{0}' to '{1}'.", source, dest));
            }
        }

        [FreeFunction("CopyFileOrDirectory")]
        private static extern bool CopyFileOrDirectoryInternal(string source, string dest);

        // Copies the file or directory following symbolic links.
        public static void CopyFileOrDirectoryFollowSymlinks(string source, string dest)
        {
            CheckForValidSourceAndDestinationArgumentsAndRaiseAnExceptionWhenNullOrEmpty(source, dest);

            if (PathExists(dest))
            {
                throw new System.IO.IOException(string.Format(
                    "Failed to Copy File / Directory from '{0}' to '{1}': destination path already exists.", source, dest));
            }

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Verify the source exists and is readable (FileUtil.PathExists(src)) before copying.
2. Check destination volume writability and free space; close other programs holding the file.
3. On Windows, shorten long paths or enable long-path support.
4. Wrap in try/catch IOException and surface the OS error / retry with back-off for transient locks.

Example fix

// before
FileUtil.CopyFileOrDirectory(src, dst);
// after
if (!FileUtil.PathExists(src)) throw new FileNotFoundException(src);
try { FileUtil.CopyFileOrDirectory(src, dst); }
catch (System.IO.IOException ex) { Debug.LogError($"copy failed: {ex.Message}"); throw; }

if (!FileUtil.PathExists(src)) throw new FileNotFoundException(src);
// ensure target volume writable/free, then:
FileUtil.CopyFileOrDirectory(src, dst);

try { FileUtil.CopyFileOrDirectory(src, dst); }
catch (System.IO.IOException ex)
{ Debug.LogError($"native copy failed for {src} -> {dst}: {ex.Message}"); throw; }

When it happens

Trigger: Source path does not exist or is inaccessible; destination volume is read-only or out of space; the source file is locked by another process; the path exceeds platform limits; a symlink loop. Any condition where the native copy returns false.

Common situations: Copying from a Library/ path that Unity has locked. Copying onto a network mount with intermittent permissions. Path longer than MAX_PATH on Windows. Source deleted between the PathExists check on dest and the copy call.

Related errors

• Failed to Copy File / Directory from '{0}' to '{1}': destina
• Failed to Move File / Directory from '{0}' to '{1}'.
• Failed to delete directory '{0}'.
• FileUtil.OpenRead: Failed to acquire UDS content for '{path}
• Value cannot be null.

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