mastra-ai/mastra · error

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

When creating a pull-request review comment that is not a reply, GitHub's API requires commitId, path, line, and side. The integration validates these fields and throws if any is missing so the request fails locally instead of with an Octokit/GitHub 422.

Source

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

      comments: response.data.map(comment => parseReviewComment(comment)),
      nextCursor: response.data.length === LIST_PAGE_SIZE ? String(page + 1) : null,
    };
  }

  async #createReviewComment(input: InputOf<'createReviewComment'>) {
    const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
    const pullNumber = requirePullRequestNumber(input.pullRequestId);
    if (input.replyToId) {
      const { data } = await octokit.pulls.createReplyForReviewComment({
        ...parts,
        pull_number: pullNumber,
        comment_id: requirePositiveId(input.replyToId, 'review comment'),
        body: input.body,
      });
      return parseReviewComment(data);
    }
    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.');
    }
    if ((input.startLine === undefined) !== (input.startSide === undefined)) {
      throw new Error('A multi-line review comment requires both startLine and startSide.');
    }
    const { data } = await octokit.pulls.createReviewComment({
      ...parts,
      pull_number: pullNumber,
      body: input.body,
      commit_id: input.commitId,
      path: input.path,
      line: input.line,
      side: input.side.toUpperCase() as 'LEFT' | 'RIGHT',
      start_line: input.startLine,
      start_side: input.startSide?.toUpperCase() as 'LEFT' | 'RIGHT' | undefined,
    });
    return parseReviewComment(data);
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide commitId (the SHA to comment on), path, line, and side for standalone review comments
2. If responding to an existing comment, set replyToId instead — location fields are then not required
3. Validate the comment payload shape before invoking the integration

Example fix

// before
await gh.createReviewComment({ connection, sourceId, pullNumber, body: 'nit', path }); // missing commitId/line/side
// after
await gh.createReviewComment({ connection, sourceId, pullNumber, body: 'nit', commitId: sha, path, line: 42, side: 'RIGHT' });

if (!input.replyToId && (!input.commitId || !input.path || input.line === undefined || !input.side)) {
  throw new Error('standalone review comment needs commitId, path, line, side');
}

function isStandaloneReviewComment(
  input: ReviewCommentInput,
): input is ReviewCommentInput & { commitId: string; path: string; line: number; side: 'LEFT' | 'RIGHT' } {
  return Boolean(input.commitId && input.path && input.line !== undefined && input.side);
}

try {
  await gh.createReviewComment(input);
} catch (e) {
  if (e.message.startsWith('A review comment requires commitId')) {
    // either fill the location fields or switch to a reply via replyToId
  } else throw e;
}

When it happens

Trigger: Calling the create-review-comment operation with replyToId unset and any of commitId, path, line (undefined), or side missing/empty — e.g. commenting on a PR without specifying the file location.

Common situations: Building comment UIs that omit side for non-reply comments; forgetting that replies do not need location fields while standalone comments do; schema drift after adding reply support where the non-reply branch was under-populated.

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

• GitHub pull requests require an owner/repository source.
• A multi-line review comment requires both startLine and star
• GitHub triage comments require an owner/repository source.
• GitHub ${resource} id must be a positive integer.
• ${message}

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