What causes "File already exists: {file}. Use --force to overwrite." in iOfficeAI/OfficeCLI?

Add --force if overwriting is intended.

iOfficeAI/OfficeCLI · error · CliException

file_exists

file_exists

Error message

File already exists: {file}. Use --force to overwrite.

What it means

The target file already exists and --force was not given. Import (and create) refuse to overwrite because the underlying OpenXML SDK Create truncates the target, which would silently destroy data on an agent retry or a mistyped path. --force opts in explicitly.

Source

Thrown at src/officecli/CommandBuilder.Import.cs:191

                {
                    ResidentClient.SendClose(fullPath);
                }
                else
                {
                    throw new CliException($"{Path.GetFileName(file)} is currently opened by a resident process. Please run 'officecli close \"{file}\"' first.")
                    {
                        Code = "file_locked",
                        Suggestion = $"Run: officecli close \"{file}\""
                    };
                }
            }

            // Refuse to silently overwrite an existing file unless --force is set.
            // OpenXML SDK's Create truncates the target otherwise, which can destroy
            // user data when an AI agent retries or mis-types the path.
            if (File.Exists(fullPath) && !force)
            {
                throw new CliException($"File already exists: {file}. Use --force to overwrite.")
                {
                    Code = "file_exists",
                    Suggestion = "Add --force flag or remove the file first."
                };
            }
            if (File.Exists(fullPath) && force)
            {
                Console.Error.WriteLine($"Overwriting existing file: {file}");
            }

            OfficeCli.BlankDocCreator.Create(file, locale, minimal);
            var fullCreatedPath = Path.GetFullPath(file);

            // If a --force overwrite replaced a file that currently has a live
            // watch session, push a full SSE refresh so the preview reflects the
            // new (blank) document instead of the stale pre-overwrite content
            // (issue #169). create replaces the whole file, so a full re-render
            // is the only correct shape — mirrors swap / refresh. Only reachable

View on GitHub (pinned to 1ced45e900)

Solutions

Add --force if overwriting is intended.
Or remove/back up the existing file first.
Make scripts idempotent: clean the target before import.

Example fix

// before
officecli import out.xlsx --file data.csv   # out.xlsx exists
// after
officecli import out.xlsx --file data.csv --force

Defensive patterns

Strategy: validation

Validate before calling

if (File.Exists(target) && !force)
    throw new IOException(
        $"Refusing to overwrite '{target}'; pass force: true or delete it.");

Try / catch

// Catch file_exists and decide: force-overwrite or skip.
try { RunImport(target, src, force: false); }
catch (CliException e) when (e.Code == "file_exists") {
    RunImport(target, src, force: true);
}

Prevention

Decide overwrite policy up front and pass --force intentionally.
Keep scripts idempotent (clean target first) to avoid the ambiguous retry.
Never blanket --force without understanding it truncates.

When it happens

Trigger: 'officecli import existing.xlsx --file data.csv' where existing.xlsx exists and no --force; re-running a script that already produced the file.

Common situations: An agent retrying an import that partially completed; a script re-run without cleanup; pointing import at an important existing workbook by mistake.

Related errors

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