{"record":{"id":"316972a6bb8706e7","repo":"iOfficeAI/OfficeCLI","slug":"file-locked","errorCode":"file_locked","errorMessage":"{Path.GetFileName(file)} is currently opened by a resident process. Please run 'officecli close \"{file}\"' first.","messagePattern":"(.+?) is currently opened by a resident process\\. Please run 'officecli close \"(.+?)\"' first\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/CommandBuilder.Import.cs","lineNumber":178,"sourceCode":"                file += ext;\n            }\n\n            // Check if the file is held by a resident process\n            var fullPath = Path.GetFullPath(file);\n            if (ResidentClient.TryConnect(fullPath, out _))\n            {\n                // Stale-resident recovery: if the on-disk file is gone (typical\n                // example-script pattern: os.remove(FILE) then `create`), the\n                // resident is pinning a path that no longer exists. Auto-close\n                // it and proceed — refusing here would force every example\n                // script to wrap `create` in a defensive `close`.\n                if (!File.Exists(fullPath))\n                {\n                    ResidentClient.SendClose(fullPath);\n                }\n                else\n                {\n                    throw new CliException($\"{Path.GetFileName(file)} is currently opened by a resident process. Please run 'officecli close \\\"{file}\\\"' first.\")\n                    {\n                        Code = \"file_locked\",\n                        Suggestion = $\"Run: officecli close \\\"{file}\\\"\"\n                    };\n                }\n            }\n\n            // Refuse to silently overwrite an existing file unless --force is set.\n            // OpenXML SDK's Create truncates the target otherwise, which can destroy\n            // user data when an AI agent retries or mis-types the path.\n            if (File.Exists(fullPath) && !force)\n            {\n                throw new CliException($\"File already exists: {file}. Use --force to overwrite.\")\n                {\n                    Code = \"file_exists\",\n                    Suggestion = \"Add --force flag or remove the file first.\"\n                };\n            }","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/CommandBuilder.Import.cs#L160-L196","documentation":"The target file is currently held open by the officecli resident server process (a long-lived handler that keeps the document loaded). Import/create refuse to proceed to avoid corrupting the resident's in-memory state. If the on-disk file is already gone it is treated as a stale resident and auto-closed; this error only fires when the file still exists and is genuinely locked.","triggerScenarios":"After a resident-mode command (e.g. an earlier 'view'/'set' with resident enabled) left the file open in the resident server, then running 'officecli import <same-file>' or 'create' over it.","commonSituations":"An agent session mixing resident and non-resident commands on the same file; a resident server left running from a prior session; forgetting to close after batch work.","solutions":["Close the resident: 'officecli close \"<file>\"', then retry.","If the resident is stale or unreachable, restart the resident server.","Structure scripts to close resident-held files before import/create."],"exampleFix":"// before\nofficecli import data.xlsx --file rows.csv   # resident holds data.xlsx\n// after\nofficecli close data.xlsx\nofficecli import data.xlsx --file rows.csv","handlingStrategy":"validation","validationCode":"if (ResidentClient.TryConnect(Path.GetFullPath(target), out _))\n{\n    ResidentClient.SendClose(Path.GetFullPath(target));\n    // optionally wait briefly for release, then proceed\n}","typeGuard":null,"tryCatchPattern":"// On CliException { Code = \"file_locked\" }: close the resident and retry once.\ntry { RunImport(target, src); }\ncatch (CliException e) when (e.Code == \"file_locked\") {\n    ResidentClient.SendClose(Path.GetFullPath(target));\n    RunImport(target, src);\n}","preventionTips":["Always 'close' resident-held files before import/create in pipelines.","Avoid mixing resident and one-shot commands on the same file in one script.","Detect 'file_locked' and auto-close+retry once."],"tags":["resident","file-lock","import","concurrency"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}