mastra-ai/mastra · error

${message}

Error message

${message}

What it means

getSingleSourceId enforces that sourceIds contains exactly one element and returns it; otherwise it rethrows the caller-supplied message. Callers pass messages like 'expects exactly one source id', so the error text is capability-specific. It guards against ambiguous multi-source or empty inputs.

Source

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

function requirePullRequestNumber(value: string): number {
  return requirePositiveId(value, 'pull request');
}

function requirePositiveId(value: string, resource: string): number {
  const parsed = parsePositiveInteger(value);
  if (parsed === null) throw new Error(`GitHub ${resource} id must be a positive integer.`);
  return parsed;
}

function getGithubInstallationId(connection: IntegrationConnection): number {
  if (connection.type !== 'app-installation') {
    throw new Error('GitHub capabilities require an app-installation connection.');
  }
  return connection.installationId;
}

function getSingleSourceId(sourceIds: string[], message: string): string {
  if (sourceIds.length !== 1) throw new Error(message);
  return sourceIds[0]!;
}

function normalizeLabels(labels: string[] | undefined): string[] {
  return [...new Set((labels ?? []).map(label => label.trim()).filter(Boolean))];
}

function requireSourceId(sourceId: string | undefined, message: string): string {
  if (!sourceId) throw new Error(message);
  return sourceId;
}

function parsePositiveCursor(cursor: string | undefined): number {
  if (cursor === undefined) return 1;
  const page = parsePositiveInteger(cursor);
  if (page === null) throw new Error('GitHub cursor must be a positive page number.');
  return page;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure exactly one source id is passed for single-source capabilities.
2. Check the caller that builds sourceIds for empty/multi-element selections.
3. Split bulk work into per-source calls.
4. Inspect the error message text — it names which capability required a single source.

Example fix

// before
await cap.run({ sourceIds: selected }); // may be 0 or many
// after
if (selected.length !== 1) throw new Error('select exactly one repository');
await cap.run({ sourceIds: [selected[0]] });

if (!Array.isArray(sourceIds) || sourceIds.length !== 1 || !sourceIds[0]) throw new Error('exactly one source id required');

function isSingleSourceId(v: unknown): v is [string] {
  return Array.isArray(v) && v.length === 1 && typeof v[0] === 'string' && v[0].length > 0;
}

try {
  await runCapability({ sourceIds });
} catch (e) {
  if ((e as Error).message.includes('exactly one')) throw new Error(`got ${sourceIds?.length ?? 0} sources, need exactly 1`);
  throw e;
}

When it happens

Trigger: Calling a capability scoped to one repository/PR with an empty sourceIds array or with multiple ids, e.g. sourceIds: [] or ['acme/a','acme/b'].

Common situations: Passing all selected sources instead of a single one; upstream filter returning zero matches; UI sending bulk selection to a single-item API.

Related errors

• GitHub pull requests require an owner/repository source.
• A review comment requires commitId, path, line, and side unl
• 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.

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