iOfficeAI/OfficeCLI · error · CliException

invalid_argument

invalid_argument

Error message

--index, --after, and --before are mutually exclusive. Use only one.

What it means

Thrown by the `add` command when more than one of the positioning options --index, --after, --before is supplied. The posCount guard counts how many are set and rejects >1 with code `invalid_argument` and a Suggestion pointing to the correct single-option usage.

Source

Thrown at src/officecli/CommandBuilder.Add.cs:75

        addCommand.SetAction(result => { var json = result.GetValue(jsonOption); return SafeRun(() =>
        {
            // CONSISTENCY(numfmt-warning): see CommandBuilder.Set.cs — collect
            // Core-layer advisory warnings for the JSON envelope.
            if (json) OfficeCli.Core.WarningContext.Begin();
            var file = result.GetValue(addFileArg)!;
            var parentPath = MsysPathHint.Restore(result.GetValue(addParentPathArg)!)!;
            var type = result.GetValue(addTypeOpt);
            var from = MsysPathHint.Restore(result.GetValue(addFromOpt));
            var index = result.GetValue(addIndexOpt);
            var after = MsysPathHint.Restore(result.GetValue(addAfterOpt));
            var before = MsysPathHint.Restore(result.GetValue(addBeforeOpt));
            var props = result.GetValue(addPropsOpt);
            var force = result.GetValue(forceOption);

            // Validate mutual exclusivity of --index, --after, --before
            var posCount = (index.HasValue ? 1 : 0) + (after != null ? 1 : 0) + (before != null ? 1 : 0);
            if (posCount > 1)
                throw new OfficeCli.Core.CliException("--index, --after, and --before are mutually exclusive. Use only one.")
                {
                    Code = "invalid_argument",
                    Suggestion = "Use --index for positional insert, or --after/--before for anchor-based insert."
                };

            InsertPosition? position = index.HasValue ? InsertPosition.AtIndex(index.Value)
                : after != null ? InsertPosition.AfterElement(after)
                : before != null ? InsertPosition.BeforeElement(before)
                : null;
            bool hadWarnings = false;

            // Check document protection for .docx files
            if (!force && file.Extension.Equals(".docx", StringComparison.OrdinalIgnoreCase))
            {
                var protectionError = CheckDocxProtection(file.FullName, parentPath, json);
                if (protectionError != 0) return protectionError;
            }

View on GitHub (pinned to 1ced45e900)

Solutions

1. Keep exactly one positioning option: --index for a numeric slot, --after to anchor behind an element, or --before to anchor ahead.
2. Drop the redundant flag from your command line.
3. If you need anchor-based insert, use --after or --before alone; for positional, use --index alone.

Example fix

# before
officecli add file.docx /body --type paragraph --index 0 --after /body/p[1]

# after
officecli add file.docx /body --type paragraph --index 0

// Count positioning options before building the command line.
int pos = (index.HasValue?1:0) + (after!=null?1:0) + (before!=null?1:0);
if (pos > 1) throw new ArgumentException("Pass only one of --index/--after/--before");

// Narrow to at most one positioning specifier.
static string? SinglePosition(int? index, string? after, string? before) =>
    (index.HasValue, after, before) switch
    {
        (true, null, null) => $"--index {index}",
        (false, string a, null) => $"--after {a}",
        (false, null, string b) => $"--before {b}",
        _ => null // invalid — caller errors
    };

When it happens

Trigger: `officecli add file.docx /body --type paragraph --index 0 --after /body/p[1]`, or `--after X --before Y`, or all three. Any combination where posCount exceeds 1.

Common situations: A user copies options from an example that used --after and pastes their own --index without removing it; an AI agent emits redundant positioning specifiers; a script template blindly includes all positioning flags.

Related errors

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

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