mastra-ai/mastra · error

${name} must be a positive integer.

Error message

${name} must be a positive integer.

What it means

`optionalPositiveIntegerEnv` reads a numeric tuning option from an environment variable and throws `${name} must be a positive integer.` when the variable is set (non-empty after trim) but does not parse to a safe positive integer. 'Optional' means absent/blank is fine (returns undefined), but a present value must be valid — the library fails fast rather than silently clamping.

Source

Thrown at mastracode/factory/src/integrations/platform/linear/integration.ts:695

  return JSON.stringify(state);
}

function requireLinearConnection(connection: IntegrationConnection): void {
  if (connection.type !== 'oauth') {
    throw new Error('Linear capabilities require an OAuth connection.');
  }
}

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

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the env var to a positive integer string, e.g. `SOME_VAR=30000`.
2. Unset the variable entirely (or leave it blank) to use the library default.
3. Fix non-integer forms: remove decimals, commas, units, and negative signs.
4. In deployment config, add a regex check `^\d+$` on these vars before deploy.

Example fix

// before (env)
LINEAR_PAGE_SIZE=0
// after (env)
LINEAR_PAGE_SIZE=100  # or unset the variable to use the default

function readPositiveIntEnv(name: string): number | undefined {
  const v = process.env[name]?.trim();
  if (!v) return undefined;
  const n = Number(v);
  if (!Number.isSafeInteger(n) || n <= 0) {
    throw new Error(`${name} must be a positive integer (got "${v}")`);
  }
  return n;
}

When it happens

Trigger: Setting a tuning env var (any name read via this helper at integration.ts:695) to '0', '-5', '3.5', 'abc', or a value beyond Number.MAX_SAFE_INTEGER, then constructing the Linear integration.

Common situations: Ops setting `SOME_VAR=0` to disable a feature; locale-formatted numbers ('1,000'); decimal milliseconds ('1500.5'); unit confusion (seconds written where milliseconds expected, e.g. '30' vs '30000' is fine but '0.03' is not).

Related errors

• Platform Linear event polling interval must be a positive nu
• Platform Linear reconcile interval must be a positive number
• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI

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