{"record":{"id":"94d43c611742170c","repo":"iOfficeAI/OfficeCLI","slug":"127-94d43c","errorCode":"127","errorMessage":"officecli CLI not found: {bin!r} is not on PATH nor in the default install location (~/.local/bin, or %LOCALAPPDATA%\\OfficeCLI on Windows). This SDK only forwards commands to the officecli binary, which must be installed separately. Install it:\n    python -m officecli install            # runs the official installer\n    # or: curl -fsSL https://d.officecli.ai/install.sh | bash\nAlready installed elsewhere? pass binary=\"/path/to/officecli\".","messagePattern":"officecli CLI not found: (.+?) is not on PATH nor in the default install location \\(~/\\.local/bin, or %LOCALAPPDATA%\\\\OfficeCLI on Windows\\)\\. This SDK only forwards commands to the officecli binary, which must be installed separately\\. Install it:\n    python -m officecli install            # runs the official installer\n    # or: curl -fsSL https://d\\.officecli\\.ai/install\\.sh \\| bash\nAlready installed elsewhere\\? pass binary=\"/path/to/officecli\"\\.","errorType":"exception","errorClass":"OfficeCliError","httpStatus":null,"severity":"error","filePath":"sdk/python/officecli.py","lineNumber":368,"sourceCode":"        for cand in filter(None, (shutil.which(binary), _install_dir_candidate(binary))):\n            if _runs_ok(cand):\n                return cand\n    return binary                          # give up; _run_cli raises the helpful error\n\n\ndef _run_cli(binary, argv):\n    \"\"\"Run `binary <argv...>` (capturing output). A missing binary surfaces as a\n    clear OfficeCliError with install guidance, not a raw FileNotFoundError.\"\"\"\n    try:\n        # text=True alone decodes with locale.getencoding() — the ANSI code page\n        # on Windows (cp936/cp1252). The CLI always writes UTF-8, so a message\n        # carrying a non-ASCII path raised UnicodeDecodeError (or mojibake) out\n        # of subprocess instead of a clean OfficeCliError. The resident-pipe\n        # route below already decodes utf-8; keep the two agreeing.\n        return subprocess.run([binary, *argv], capture_output=True,\n                              text=True, encoding=\"utf-8\", errors=\"replace\")\n    except FileNotFoundError:\n        raise OfficeCliError(127, _MISSING_CLI.format(bin=binary)) from None\n\n\n# ---------------------------------------------------------------- the shell\nclass Document:\n    def __init__(self, path, binary=\"officecli\", timeout=30.0):\n        # Canonical (Windows 8.3-expanded) so the pipe name AND the _serves()\n        # path comparison both match what the resident reports.\n        self.path = _canonical_path(path)\n        self.bin = _resolve_binary(binary)\n        self.timeout = timeout          # connect timeout (s); the reply read blocks\n        self._main, self._ping = pipe_paths(self.path)\n        self._restart_lock = threading.Lock()   # serialize dead-resident restarts\n        self._start()\n\n    def _start(self):\n        # If a resident is ALREADY serving this file, reuse it — no process spawn.\n        # Mirrors officecli, where a command after `create` reuses the resident\n        # `create` auto-started instead of re-running `open`. _serves() is a real","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/sdk/python/officecli.py#L350-L386","documentation":"Raised by the Python SDK (code 127) when the officecli binary cannot be found: subprocess.run raises FileNotFoundError because the binary is neither on PATH nor in the default install location (~/.local/bin on Unix, %LOCALAPPDATA%\\OfficeCLI on Windows). The SDK only forwards commands to the separately-installed officecli binary, so it surfaces clear install guidance rather than a raw FileNotFoundError.","triggerScenarios":"Using the SDK (officecli.open/create/Document) before installing the officecli binary; binary installed in a non-default location not on PATH; CI/container image missing the binary.","commonSituations":"Fresh environment without the CLI; a venv/PATH that excludes ~/.local/bin; a Docker image that installed the Python SDK but not the native binary.","solutions":["Install the binary: python -m officecli install (or the documented curl/PowerShell installer).","If installed elsewhere, pass binary='/path/to/officecli' to open/create/Document.","Ensure the install location is on PATH (export PATH=\"$HOME/.local/bin:$PATH\")."],"exampleFix":"# before\ndoc = officecli.open('book.xlsx')   # binary missing\n# after\nofficecli.install()                  # installs the officecli binary\ndoc = officecli.open('book.xlsx')\n# or point at an existing binary\ndoc = officecli.Document('book.xlsx', binary='/opt/officecli/bin/officecli')","handlingStrategy":"fallback","validationCode":"import shutil, officecli\n\ndef resolve_binary(explicit=None):\n    if explicit and shutil.which(explicit):\n        return explicit\n    if shutil.which('officecli'):\n        return 'officecli'\n    raise officecli.OfficeCliError(127, 'officecli binary not found — run officecli.install()')\n\nresolve_binary()  # call before opening a Document","typeGuard":"import shutil\ndef officecli_available(binary='officecli'):\n    return shutil.which(binary) is not None","tryCatchPattern":"try:\n    doc = officecli.open('book.xlsx')\nexcept officecli.OfficeCliError as e:\n    if e.code == 127:\n        officecli.install()           # then retry open\n        doc = officecli.open('book.xlsx')\n    else:\n        raise","preventionTips":["Install the officecli binary (python -m officecli install) before using the SDK.","Ensure ~/.local/bin (Unix) or the Windows install dir is on PATH.","Pass binary='/path/to/officecli' when installed in a non-default location."],"tags":["python-sdk","install","binary-not-found","setup","path"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}