A review comment requires commitId, path, line, and side unl

Error message

A review comment requires commitId, path, line, and side unless it is a reply.

What it means

Thrown by the private #createReviewComment helper when creating a (non-reply) GitHub pull request review comment without the required fields: commitId, path, line, and side. GitHub's API needs these to anchor the comment to a diff position; replies are exempt because they anchor to the parent comment instead.

Source

Thrown at mastracode/factory/src/integrations/platform/github/integration.ts:1371

  async #listReviewComments(input: ListReviewCommentsInput) {
    const page = parsePositiveCursor(input.cursor);
    const result = await this.#client.request<{ comments: GithubReviewComment[] }>(
      'GET',
      `${pullRequestPath(input, input.pullRequestId)}/comments?page=${page}&per_page=${PAGE_SIZE}`,
    );
    return {
      comments: result.comments.map(parseReviewComment),
      nextCursor: result.comments.length === PAGE_SIZE ? String(page + 1) : null,
    };
  }

  async #createReviewComment(input: CreateReviewCommentInput) {
    let body: Record<string, unknown>;
    if (input.replyToId !== undefined) {
      body = { body: input.body, replyToId: requirePositiveId(input.replyToId, 'review comment') };
    } else {
      if (!input.commitId || !input.path || input.line === undefined || !input.side) {
        throw new Error('A review comment requires commitId, path, line, and side unless it is a reply.');
      }
      body = {
        body: input.body,
        commitId: input.commitId,
        path: input.path,
        line: input.line,
        side: input.side.toUpperCase(),
        startLine: input.startLine,
        startSide: input.startSide?.toUpperCase(),
      };
    }
    return parseReviewComment(
      await this.#client.request<GithubReviewComment>(
        'POST',
        `${pullRequestPath(input, input.pullRequestId)}/comments`,
        body,
        { actingUserId: input.actingUserId },
      ),

View on GitHub (pinned to 75dd419e61)

Solutions

Populate commitId, path, line, and side on the input before calling the API
If responding to an existing comment, set replyToId instead of the anchoring fields
Validate the input shape before invoking (see validationCode)
Fetch the commit SHA of the reviewed head to supply commitId

Example fix

// before
await github.createReviewComment({ installationId, sourceId, pullRequestId, body: 'nit:' });
// after
await github.createReviewComment({ installationId, sourceId, pullRequestId, body: 'nit:', commitId: headSha, path: 'src/index.ts', line: 42, side: 'RIGHT' });

Defensive patterns

Strategy: validation

Validate before calling

function validateReviewComment(input: CreateReviewCommentInput): string | null {
  if (input.replyToId !== undefined) return null;
  if (!input.commitId) return 'commitId is required';
  if (!input.path) return 'path is required';
  if (input.line === undefined) return 'line is required';
  if (!input.side) return 'side is required';
  return null;
}

Type guard

function isAnchoredReviewComment(i: CreateReviewCommentInput): boolean {
  return i.replyToId !== undefined || (!!i.commitId && !!i.path && i.line !== undefined && !!i.side);
}

Try / catch

try {
  await github.createReviewComment(input);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('A review comment requires')) {
    // fall back to posting a plain PR comment or prompt the user for line/side
  } else throw err;
}

Prevention

Always capture head commit SHA, file path, line, and side when building review UI state
Prefer replyToId for threaded responses instead of duplicating anchor fields
Validate comment inputs in the UI before submitting
Treat line/side as required form fields for new (non-reply) comments

When it happens

Trigger: Calling the review-comment capability with input.replyToId undefined and any of commitId empty, path empty, line undefined, or side missing.

Common situations: Tool/agent calls that build the comment body but skip diff-position fields; UI flows where the user picks a file but never selects a line/side; passing line: 0 or empty-string path from unvalidated input.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/d909b2dd7de8500b. Report an issue: GitHub.