google-gemini/gemini-cli · error · FatalInputError

Exiting due to an error processing the @ command.

Error message

Exiting due to an error processing the @ command.

What it means

Thrown in the non-interactive CLI path when handleAtCommand() returns an error string or a null processedQuery. It is a FatalInputError (exit code 42). The @-command processor failed to resolve a file path, MCP resource, or agent referenced via @-syntax, and the error is surfaced here because non-interactive mode cannot recover from a missing include.

Source

Thrown at packages/cli/src/nonInteractiveCli.ts:293

          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
          query = slashCommandResult as Part[];
        }
      }

      if (!query) {
        const { processedQuery, error } = await handleAtCommand({
          query: input,
          config,
          addItem: (_item, _timestamp) => 0,
          onDebugMessage: () => {},
          messageId: Date.now(),
          signal: abortController.signal,
          escapePastedAtSymbols: false,
        });
        if (error || !processedQuery) {
          // An error occurred during @include processing (e.g., file not found).
          // The error message is already logged by handleAtCommand.
          throw new FatalInputError(
            error || 'Exiting due to an error processing the @ command.',
          );
        }
        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
        query = processedQuery as Part[];
      }

      // Emit user message event for streaming JSON
      if (streamFormatter) {
        streamFormatter.emitEvent({
          type: JsonStreamEventType.MESSAGE,
          timestamp: new Date().toISOString(),
          role: 'user',
          content: input,
        });
      }

      let currentMessages: Content[] = [{ role: 'user', parts: query }];

View on GitHub (pinned to 5024443c72)

Solutions

1. Check stderr/debug log: handleAtCommand already logged the specific resolution error before this throw.
2. Verify the @-referenced path exists, is inside the workspace root, and matches an allowed glob.
3. For @-resources, confirm the MCP server is connected and the resource name is correct.
4. Remove the @-include or use an absolute/relative path that resolves to a real file.

Example fix

# before
gemini -p "@src/old-name.ts explain this"
# after
gemini -p "@src/renamed-file.ts explain this"

import fs from 'node:fs';
import path from 'node:path';

function atIncludesExist(query: string, root: string): { ok: boolean; missing: string[] } {
  const missing: string[] = [];
  for (const m of query.matchAll(/@([\w./\\-]+\.[\w]+)/g)) {
    const p = m[1];
    if (!fs.existsSync(path.resolve(root, p))) missing.push(p);
  }
  return { ok: missing.length === 0, missing };
}

function isHandleAtResult(v: { processedQuery: unknown; error?: string }): v is { processedQuery: NonNullable<typeof v.processedQuery>; error?: undefined } {
  return !!v.processedQuery && !v.error;
}

try {
  await runNonInteractive(input);
} catch (e) {
  if (e instanceof FatalInputError && /@ command/.test(e.message)) {
    // exit code 42: a referenced @-file/resource was unresolvable; check the prior log line
  }
  throw e;
}

When it happens

Trigger: Running `gemini -p "@missing.txt ..."` (or a prompt containing @path/@resource/@agent) where resolveFilePaths/readLocalFiles/readMcpResources returned fileResult.error or mcpResult.error, so handleAtCommand returns { processedQuery: null, error }.

Common situations: Typo in an @-included file path; the file is outside the workspace/glob roots and got filtered out; an MCP resource name is wrong or the MCP server is down; pasting @-syntax that resolves to zero valid targets.

Related errors

• Exiting due to an error processing the @ command.
• Exiting due to command result that is not supported in non-i
• Workspace path ${resolvedPath} does not exist
• Workspace path ${resolvedPath} is not a directory
• tar.c command failed to create ${tmpArchiveFile}

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/38016c5e2a5363fc. Report an issue: GitHub.