modelcontextprotocol/servers · error · Error

Cannot specify both head and tail parameters simultaneously

Error message

Cannot specify both head and tail parameters simultaneously

What it means

Thrown by the filesystem server's `read_text_file`/`read_file` handler when a request supplies both `head` and `tail` in the same call. The two are mutually exclusive read modes: `head` reads the first N lines, `tail` reads the last N lines. Supplying both is ambiguous, so the server rejects it before any I/O.

Source

Thrown at src/filesystem/index.ts:195

    stream.on('data', (chunk) => {
      chunks.push(chunk as Buffer);
    });
    stream.on('end', () => {
      const finalBuffer = Buffer.concat(chunks);
      resolve(finalBuffer.toString('base64'));
    });
    stream.on('error', (err) => reject(err));
  });
}

// Tool registrations

// read_file (deprecated) and read_text_file
const readTextFileHandler = async (args: z.infer<typeof ReadTextFileArgsSchema>) => {
  const validPath = await validatePath(args.path);

  if (args.head && args.tail) {
    throw new Error("Cannot specify both head and tail parameters simultaneously");
  }

  let content: string;
  if (args.tail) {
    content = await tailFile(validPath, args.tail);
  } else if (args.head) {
    content = await headFile(validPath, args.head);
  } else {
    content = await readFileContent(validPath);
  }

  return {
    content: [{ type: "text" as const, text: content }],
    structuredContent: { content }
  };
};

server.registerTool(

View on GitHub (pinned to 76d64c822f)

Solutions

1. Send only one of `head` or `tail` per call; omit the other.
2. If you need both the start and end of a file, issue two separate calls.
3. Validate the args before sending: `!(args.head && args.tail)`.

Example fix

// before
{ path: '/var/log/syslog', head: 10, tail: 10 }
// after (two calls)
{ path: '/var/log/syslog', head: 10 }
{ path: '/var/log/syslog', tail: 10 }

if (args.head && args.tail) {
  throw new Error('Specify only one of head or tail');
}
// or simply delete one before sending
const { head, ...rest } = args;
if (args.tail) { delete rest.head; }

When it happens

Trigger: Calling `read_text_file` (or deprecated `read_file`) with both `head` and `tail` set to positive integers in one request, e.g. `{ path: '/x', head: 10, tail: 10 }`.

Common situations: LLMs or clients that default-fill both optional fields, a UI that lets users toggle both options, or a refactor that merges two code paths without clearing the other flag.

Related errors

• Invalid resourceType: ${args?.resourceType}. Must be ${RESOU
• Invalid resourceId: ${args?.resourceId}. Must be a finite po
• Unknown outputType: ${outputType}
• Access denied - path outside allowed directories: ${absolute
• Access denied - parent directory outside allowed directories

AI-assisted analysis of modelcontextprotocol/servers@76d64c822f (2026-08-12). Data as JSON: /api/errors/3cf73f11699aa637. Report an issue: GitHub.