iOfficeAI/OfficeCLI · error · CliException

file_not_found

file_not_found

Error message

File not found: {filePath}

What it means

Thrown by DocumentHandlerFactory.Open when filePath is non-empty but File.Exists returns false. This is the standard 'file does not exist on disk' error, distinguished from error 443 (file_required) which catches empty/null paths. The suggestion recommends using an absolute path or a path relative to the current working directory, and the help text points to the 'create' command for users who intended to make a new document.

Source

Thrown at src/officecli/Handlers/DocumentHandlerFactory.cs:33

    {
        // An empty/whitespace path otherwise falls through to File.Exists →
        // "File not found: " with a blank tail, which actively misleads: the
        // caller can't tell the file is *missing as an argument* from *present
        // but wrong*. The single most common way to hit this is an MCP/batch
        // call that omits the top-level `file` (e.g. a model that replicates the
        // single-command shape and puts `file` inside each batch item instead).
        // Give one clear, project-wide message at the shared open chokepoint.
        if (string.IsNullOrWhiteSpace(filePath))
            throw new CliException("No document file specified — the file path is required. "
                + "In MCP/batch, pass `file` as the top-level argument (it applies to every command); "
                + "do not put `file` inside individual batch commands.")
            {
                Code = "file_required",
                Suggestion = "Provide the document path as the top-level file argument."
            };

        if (!File.Exists(filePath))
            throw new CliException($"File not found: {filePath}")
            {
                Code = "file_not_found",
                Suggestion = "Check the file path. Use an absolute path or a path relative to the current directory.",
                Help = "officecli create <path> --type docx|xlsx|pptx"
            };

        // CONSISTENCY(corrupt-file-rejection): a 0-byte file is silently
        // accepted by Open XML SDK 3.x in read-write mode (it materialises an
        // empty Package), but the resulting handler returns a fake root node
        // with no parts. CLI commands that follow then report success and
        // exit 0 even though the document is unusable. Reject the file
        // up-front so the same file_not_found / corrupt_file UX applies that
        // direct-mode (read-only) Open already gave for 0-byte files.
        if (new FileInfo(filePath).Length == 0)
            throw new CliException($"Cannot open {Path.GetFileName(filePath)}: file is 0 bytes (not a valid Office document).")
            {
                Code = "corrupt_file",
                Suggestion = "Recreate the file with: officecli create <path>"

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use an absolute path (e.g. /home/user/docs/report.docx or C:\Users\user\docs\report.docx) to eliminate working-directory ambiguity.
2. If the file should exist, verify with 'ls -la <path>' or 'dir <path>' from the same working directory the CLI/MCP server uses.
3. If you intended to create a new document, use 'officecli create <path> --type docx|xlsx|pptx' instead.
4. On Linux/macOS, check filename casing — the path is case-sensitive on these platforms.

// Validate file existence before opening
if (!File.Exists(filePath))
    throw new FileNotFoundException($"File not found: {filePath}");
var handler = DocumentHandlerFactory.Open(filePath);

static bool FileExists(string? path) => !string.IsNullOrWhiteSpace(path) && File.Exists(path);

try
{
    var handler = DocumentHandlerFactory.Open(filePath);
}
catch (CliException ex) when (ex.Code == "file_not_found")
{
    // Resolve to absolute path and retry, or report to the caller
    var abs = Path.GetFullPath(filePath);
    logger.LogError("File not found at {Path} (absolute: {Abs}). Check working directory: {Cwd}",
        filePath, abs, Environment.CurrentDirectory);
    throw;
}

When it happens

Trigger: Calling Open with a path that points to a nonexistent file. Common causes: relative path resolved from an unexpected working directory, a typo in the filename, the file was on a network share that is now disconnected, or the path uses a different casing on a case-sensitive filesystem (the .NET File.Exists is case-insensitive on Windows but case-sensitive on Linux/macOS).

Common situations: Running the CLI from a different directory than expected so a relative path resolves wrong; the MCP server running in a container where the file mount path differs; a filename with a trailing space or special character from a shell glob expansion; a file on a network drive (UNC path) where the connection dropped.

Related errors

• Input file not found: {inputFile.FullName}
• file_not_found
• file_not_found
• file_not_found
• File not found: {path}

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/0d05a0749569162f. Report an issue: GitHub.