What causes "${name} must be a positive integer." in mastra-ai/mastra?

Set the variable to plain positive integer milliseconds, e.g. MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS=30000

${name} must be a positive integer.

Error message

${name} must be a positive integer.

What it means

Thrown by optionalPositiveIntegerEnv when the MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS environment variable is set but does not parse as a positive integer. The library fails fast at configuration time so a typo'd interval (e.g. '5s', '0', '') never silently disables or breaks polling.

Source

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

  if (!/^\d+$/.test(value)) return null;
  const parsed = Number(value);
  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
}

function parseGithubExternalTarget(externalId: string): { repository: string; issueId: string } | null {
  const match =
    externalId.match(/^(.+\/.+):(\d+)$/) ??
    externalId.match(/^github:(\d+):(?:issue|pull-request):(\d+)$/) ??
    externalId.match(/^(\d+):(\d+)$/);
  if (!match?.[1] || !match[2] || parsePositiveInteger(match[2]) === null) return null;
  return { repository: match[1], issueId: match[2] };
}

function optionalPositiveIntegerEnv(name: 'MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS'): number | undefined {
  const value = process.env[name]?.trim();
  if (!value) return undefined;
  const parsed = parsePositiveInteger(value);
  if (parsed === null) throw new Error(`${name} must be a positive integer.`);
  return parsed;
}

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 reviewEvent(event: 'approve' | 'request-changes' | 'comment') {
  if (event === 'approve') return 'APPROVE' as const;
  if (event === 'request-changes') return 'REQUEST_CHANGES' as const;
  return 'COMMENT' as const;
}

function isNotFound(error: unknown): boolean {
  return error instanceof PlatformApiError && error.status === 404;
}

View on GitHub (pinned to 75dd419e61)

Solutions

Set the variable to plain positive integer milliseconds, e.g. MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS=30000
Remove the variable entirely to use the built-in default interval
Check the runtime environment (docker env, .env file) for stray characters and strip units/separators
Restart the process after fixing so the integration constructor re-reads the env

Example fix

// before (in .env)
MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS=30s
// after
MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS=30000

Defensive patterns

Strategy: validation

Validate before calling

const raw = process.env.MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS;
if (raw !== undefined && !/^\d+$/.test(raw.trim())) {
  throw new Error(`MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS must be integer milliseconds, got: ${raw}`);
}

Try / catch

try {
  const integration = new PlatformGithubIntegration({ pollingIntervalMsEnv: true /* reads env */ });
} catch (err) {
  if (err instanceof Error && err.message.includes('must be a positive integer')) {
    console.error(`Bad env config: ${err.message}; unset the var to use the default interval`);
  } else throw err;
}

Prevention

Document the variable as plain integer milliseconds (no units)
Validate env vars at deploy/lint time, not just runtime
Use dotenv with strict parsing to catch malformed values
Strip commas/units in your own config layer before the library reads it

When it happens

Trigger: Setting MASTRA_PLATFORM_GITHUB_POLLING_INTERVAL_MS to a non-integer value such as '1000ms', '0', '-500', '1e3', or a value with stray characters/whitespace-only content that still fails the digit check after trim.

Common situations: Including units in the value ('30000ms' instead of '30000'); using scientific notation; docker-compose YAML quoting numbers as strings with hidden characters; copy-pasting with thousands separators ('1,000').

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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