{"record":{"id":"0d05a0749569162f","repo":"iOfficeAI/OfficeCLI","slug":"file-not-found-0d05a0","errorCode":"file_not_found","errorMessage":"File not found: {filePath}","messagePattern":"File not found: (.+?)","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/DocumentHandlerFactory.cs","lineNumber":33,"sourceCode":"    {\n        // An empty/whitespace path otherwise falls through to File.Exists →\n        // \"File not found: \" with a blank tail, which actively misleads: the\n        // caller can't tell the file is *missing as an argument* from *present\n        // but wrong*. The single most common way to hit this is an MCP/batch\n        // call that omits the top-level `file` (e.g. a model that replicates the\n        // single-command shape and puts `file` inside each batch item instead).\n        // Give one clear, project-wide message at the shared open chokepoint.\n        if (string.IsNullOrWhiteSpace(filePath))\n            throw new CliException(\"No document file specified — the file path is required. \"\n                + \"In MCP/batch, pass `file` as the top-level argument (it applies to every command); \"\n                + \"do not put `file` inside individual batch commands.\")\n            {\n                Code = \"file_required\",\n                Suggestion = \"Provide the document path as the top-level file argument.\"\n            };\n\n        if (!File.Exists(filePath))\n            throw new CliException($\"File not found: {filePath}\")\n            {\n                Code = \"file_not_found\",\n                Suggestion = \"Check the file path. Use an absolute path or a path relative to the current directory.\",\n                Help = \"officecli create <path> --type docx|xlsx|pptx\"\n            };\n\n        // CONSISTENCY(corrupt-file-rejection): a 0-byte file is silently\n        // accepted by Open XML SDK 3.x in read-write mode (it materialises an\n        // empty Package), but the resulting handler returns a fake root node\n        // with no parts. CLI commands that follow then report success and\n        // exit 0 even though the document is unusable. Reject the file\n        // up-front so the same file_not_found / corrupt_file UX applies that\n        // direct-mode (read-only) Open already gave for 0-byte files.\n        if (new FileInfo(filePath).Length == 0)\n            throw new CliException($\"Cannot open {Path.GetFileName(filePath)}: file is 0 bytes (not a valid Office document).\")\n            {\n                Code = \"corrupt_file\",\n                Suggestion = \"Recreate the file with: officecli create <path>\"","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/DocumentHandlerFactory.cs#L15-L51","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Use an absolute path (e.g. /home/user/docs/report.docx or C:\\Users\\user\\docs\\report.docx) to eliminate working-directory ambiguity.","If the file should exist, verify with 'ls -la <path>' or 'dir <path>' from the same working directory the CLI/MCP server uses.","If you intended to create a new document, use 'officecli create <path> --type docx|xlsx|pptx' instead.","On Linux/macOS, check filename casing — the path is case-sensitive on these platforms."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate file existence before opening\nif (!File.Exists(filePath))\n    throw new FileNotFoundException($\"File not found: {filePath}\");\nvar handler = DocumentHandlerFactory.Open(filePath);","typeGuard":"static bool FileExists(string? path) => !string.IsNullOrWhiteSpace(path) && File.Exists(path);","tryCatchPattern":"try\n{\n    var handler = DocumentHandlerFactory.Open(filePath);\n}\ncatch (CliException ex) when (ex.Code == \"file_not_found\")\n{\n    // Resolve to absolute path and retry, or report to the caller\n    var abs = Path.GetFullPath(filePath);\n    logger.LogError(\"File not found at {Path} (absolute: {Abs}). Check working directory: {Cwd}\",\n        filePath, abs, Environment.CurrentDirectory);\n    throw;\n}","preventionTips":["Use absolute paths to eliminate working-directory ambiguity, especially in MCP server contexts.","Verify file existence in your script before invoking the CLI: test -f \"$FILE_PATH\".","On case-sensitive filesystems (Linux/macOS), match the exact filename casing.","For network/UNC paths, verify the share is mounted and accessible from the CLI's working directory."],"tags":["file-handling","file-not-found","path-resolution"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}