EllanJiang/GameFramework · error · GameFrameworkException

Full path is invalid.

Error message

Full path is invalid.

What it means

The private FileSystem constructor requires a valid non-empty full path identifying the archive on disk. An empty or null fullPath cannot be used to open or create the archive, so GameFramework throws immediately.

Solutions

1. Pass a complete absolute path including the archive file name to Create/Open
2. Check that the config/source of the path (e.g. Application.persistentDataPath equivalent) is populated
3. Combine a validated directory with Path.Combine(dir, fileName) to guarantee a non-empty full path
4. Guard with string.IsNullOrEmpty before calling the FileSystem API

Example fix

// before
FileSystem.Create(savePath, FileSystemAccess.Write, stream, ...); // savePath may be ""
// after
string fullPath = System.IO.Path.Combine(dataDir, "game.dat");
if (string.IsNullOrEmpty(fullPath)) throw new InvalidOperationException("fullPath required");
FileSystem.Create(fullPath, FileSystemAccess.Write, stream, ...);

if (string.IsNullOrEmpty(fullPath)) throw new ArgumentException("fullPath is required", nameof(fullPath));
FileSystem.Create(fullPath, access, stream, maxFileCount, maxBlockCount);

bool IsValidFullPath(string p) => !string.IsNullOrEmpty(p);

try { var fs = FileSystem.Create(fullPath, access, stream, fc, bc); }
catch (GameFrameworkException ex) when (ex.Message == "Full path is invalid.") { Log.Error("Archive path not configured"); }

When it happens

Trigger: Calling FileSystem.Create or FileSystem.Open (public entry points) with null/empty fullPath, which flows into this private constructor.

Common situations: Path built from unset config values (e.g. missing persistent-data path) yielding empty string; concatenation where a directory segment was empty; refactoring that dropped the file name component.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Offset is invalid.
• Length is invalid.
• String ' ' is too long.
• Access is invalid.
• Stream is invalid.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/947487ee5232035f. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/FileSystem/FileSystem.cs:55

        private readonly Queue<int> m_FreeStringIndexes;
        private readonly Queue<StringData> m_FreeStringDatas;

        private HeaderData m_HeaderData;
        private int m_BlockDataOffset;
        private int m_StringDataOffset;
        private int m_FileDataOffset;

        /// <summary>
        /// 初始化文件系统的新实例。
        /// </summary>
        /// <param name="fullPath">文件系统完整路径。</param>
        /// <param name="access">文件系统访问方式。</param>
        /// <param name="stream">文件系统流。</param>
        private FileSystem(string fullPath, FileSystemAccess access, FileSystemStream stream)
        {
            if (string.IsNullOrEmpty(fullPath))
            {
                throw new GameFrameworkException("Full path is invalid.");
            }

            if (access == FileSystemAccess.Unspecified)
            {
                throw new GameFrameworkException("Access is invalid.");
            }

            if (stream == null)
            {
                throw new GameFrameworkException("Stream is invalid.");
            }

            m_FullPath = fullPath;
            m_Access = access;
            m_Stream = stream;
            m_FileDatas = new Dictionary<string, int>(StringComparer.Ordinal);
            m_BlockDatas = new List<BlockData>();
            m_FreeBlockIndexes = new GameFrameworkMultiDictionary<int, int>();

View on GitHub (pinned to d0c010b051)