iOfficeAI/OfficeCLI · error · CliException

file_required

file_required

Error message

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.

What it means

Thrown by DocumentHandlerFactory.Open when filePath is null, empty, or whitespace. This is the shared chokepoint for every CLI command and MCP/batch invocation — it catches the case where the top-level 'file' argument was omitted entirely, which would otherwise fall through to File.Exists and produce a misleading 'File not found: ' message with a blank tail. The error message specifically addresses the most common MCP/batch misuse: putting 'file' inside individual batch command items instead of as the top-level argument.

Source

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

using System.Text.RegularExpressions;
using OfficeCli.Core;
using OfficeCli.Core.Plugins;

namespace OfficeCli.Handlers;

public static class DocumentHandlerFactory
{
    public static IDocumentHandler Open(string filePath, bool editable = false)
    {
        // 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

View on GitHub (pinned to 1ced45e900)

Solutions

1. In MCP/batch: pass 'file' as the top-level key in the request, not inside each command: {"file": "path.docx", "commands": [{...}]}
2. In CLI: ensure the file path argument is provided before the subcommand arguments.
3. Check for unset environment variables: use a default or fail with a clear message before calling the CLI.
4. If calling programmatically, assert filePath is non-empty before invoking Open.

Example fix

// before (MCP batch — file nested inside commands, top-level file is absent)
{
  "commands": [
    { "op": "add", "path": "/p1", "file": "report.docx", "text": "Hello" }
  ]
}

// after (file at top level, applies to all commands)
{
  "file": "report.docx",
  "commands": [
    { "op": "add", "path": "/p1", "text": "Hello" }
  ]
}

// Validate before calling Open
if (string.IsNullOrWhiteSpace(filePath))
    throw new ArgumentException("File path is required.");
var handler = DocumentHandlerFactory.Open(filePath);

static bool IsValidFilePath(string? path) => !string.IsNullOrWhiteSpace(path);

try
{
    var handler = DocumentHandlerFactory.Open(filePath);
}
catch (CliException ex) when (ex.Code == "file_required")
{
    // The file argument was missing — for MCP/batch, move 'file' to the top level
    logger.LogError("Missing file argument. In MCP/batch, pass file at the top level, not inside each command.");
    throw;
}

When it happens

Trigger: Calling Open(null), Open(""), or Open(" "). In MCP/batch mode, this happens when the caller structures the request with 'file' nested inside each command item (e.g. {"commands": [{"op": "add", "file": "doc.docx", ...}]}) rather than at the top level ({"file": "doc.docx", "commands": [...]}). In CLI mode, running a command that requires a file without specifying the --file flag.

Common situations: An LLM model replicating the single-command shape and nesting 'file' inside batch items; a script that conditionally sets the file variable but hits a code path where it stays null; a CI pipeline passing an empty environment variable expansion (e.g. $FILE_PATH where the env var is unset).

Related errors

• invalid_argument
• missing_argument
• batch: --commands and --input are mutually exclusive. Pick o
• invalid_format
• invalid_value

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