iOfficeAI/OfficeCLI · error · ArgumentException

Path not found: {path}

Error message

Path not found: {path}

What it means

Fallback message thrown by ExecuteBatchItem for a batch "get" step when handler.Get returned a node whose Type is "error" AND whose Text is null. Get returns error-typed nodes (e.g. a named range that does not exist) instead of throwing; the batch executor converts that into an exception so --stop-on-error can detect the failure. This specific string is only used when the node carried no detail text.

Source

Thrown at src/officecli/CommandBuilder.cs:948

        switch (item.Command.ToLowerInvariant())
        {
            // NEWLINE-SEMANTICS-V2: version-stamp items are normally stripped
            // by BatchCompat.PrepareForReplay; tolerate one that reaches the
            // executor (plugin NDJSON lines bypass the list-level prepare).
            case "meta":
                return "meta";
            case "get":
            {
                var path = item.Path ?? "/";
                var depth = item.Depth ?? 1;
                var node = handler.Get(path, depth);
                // Error-typed nodes (e.g. namedrange not found) must surface as
                // exceptions so --stop-on-error can detect them. Without this,
                // Get returns a node with Type="error" and a message in Text,
                // ExecuteBatchItem treats it as success, and stop-on-error never fires.
                if (node.Type == "error")
                    throw new ArgumentException(node.Text ?? $"Path not found: {path}");
                // Unified envelope: batch get items emit the same
                // {matches, results: [...]} shape as query items, so callers
                // can consume batch step output with a single parser.
                if (format == OutputFormat.Json)
                    return OfficeCli.Core.OutputFormatter.FormatNodes(new List<DocumentNode> { node }, format);
                return OfficeCli.Core.OutputFormatter.FormatNode(node, format);
            }
            case "query":
            {
                // `path` is accepted as an alias for `selector` — the generic
                // field table says "path (set/remove/get target)" and users
                // carry it over to query; ignoring it silently ran an EMPTY
                // selector, i.e. returned every node as if the predicate
                // matched (the most dangerous kind of wrong data). Neither
                // field present is an error, mirroring the required CLI arg.
                var selector = item.Selector ?? item.Path ?? "";
                if (string.IsNullOrEmpty(selector))
                    throw new ArgumentException("'query' command requires 'selector' field. Example: {\"command\": \"query\", \"selector\": \"row[Score>80]\"}");

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Verify the path exists with a query first (`officecli query file "<selector>"`).
  2. Regenerate the batch from a fresh dump of the current document.
  3. Fix the path typo or update it to the renamed target.
  4. Confirm you are operating on the intended file/version.

Example fix

// before
{"command":"get","path":"/namedrange[Sales]"}   // renamed to Revenue
// after
{"command":"get","path":"/namedrange[Revenue]"}
Defensive patterns

Strategy: validation

Validate before calling

// Probe the path with a cheap query before issuing a get step.
var exists = handler.Query(path).Any();
if (!exists) throw new ArgumentException($"Path not found: {path}");

Try / catch

try { ExecuteBatchItem(handler, item, json); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Path not found"))
{ /* skip or mark step failed; continue batch */ }

Prevention

When it happens

Trigger: {"command":"get","path":"/namedrange[DoesNotExist]"} where the handler returns an error node with no Text; a path referencing a node that was renamed or deleted; a typo in the path.

Common situations: Batch generated from a stale document dump where paths no longer exist; renamed styles/named ranges/sheets; wrong file with a different structure; off-by-one in an index expression.

Related errors

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