mastra-ai/mastra · warning · ProcessMemoryDiagnosticsConfigError

${name} must be an integer ${range}; received ${JSON.stringi

Error message

${name} must be an integer ${range}; received ${JSON.stringify(raw)}.

What it means

ProcessMemoryDiagnosticsConfigError thrown by parseBoundedInteger when a MASTRACODE_PROFILE_* environment variable is set but is not a valid safe integer within the allowed range (minimum from PROCESS_MEMORY_DIAGNOSTICS_MINIMUMS, maximum of 2147483647 for interval values). The library validates env-supplied tuning values instead of silently clamping them, so a bad value aborts configuration. The message names the variable, the expected range, and the raw value received.

Source

Thrown at mastracode/sdk/src/process-memory-diagnostics.ts:116

}

function isEnabled(value: string | undefined): boolean {
  return ['1', 'true', 'yes', 'on'].includes(value?.trim().toLowerCase() ?? '');
}

function parseBoundedInteger(
  env: ProcessMemoryDiagnosticsEnvironment,
  name: keyof ProcessMemoryDiagnosticsEnvironment,
  fallback: number,
  minimum: number,
  maximum?: number,
): number {
  const raw = env[name];
  if (raw === undefined || raw.trim() === '') return fallback;
  const value = Number(raw);
  if (!Number.isSafeInteger(value) || value < minimum || (maximum !== undefined && value > maximum)) {
    const range = maximum === undefined ? `greater than or equal to ${minimum}` : `between ${minimum} and ${maximum}`;
    throw new ProcessMemoryDiagnosticsConfigError(
      `${name} must be an integer ${range}; received ${JSON.stringify(raw)}.`,
    );
  }
  return value;
}

function getDefaultProfileParentDirectory(): string {
  if (process.env.MASTRA_APP_DATA_DIR) return join(process.env.MASTRA_APP_DATA_DIR, 'profiles');

  const baseDirectory =
    platform === 'darwin'
      ? join(homedir(), 'Library', 'Application Support')
      : platform === 'win32'
        ? process.env.APPDATA || join(homedir(), 'AppData', 'Roaming')
        : process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
  return join(baseDirectory, 'mastracode', 'profiles');
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Correct the env variable to a plain integer string within range, e.g. MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS=10000
2. Remove the variable to fall back to the defaults (sample 10000ms, capture 300000ms, allocation 524288 bytes)
3. Check the message for the exact allowed range: intervals must be 1..2147483647 (sample), 10000..2147483647 (capture), allocation >=32768

Example fix

// before
MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS=10s
// after
MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS=10000

function validateProfileEnv(env: NodeJS.ProcessEnv = process.env): string[] {
  const issues: string[] = [];
  const check = (name: string, min: number) => {
    const raw = env[name];
    if (raw === undefined || raw.trim() === '') return;
    const v = Number(raw);
    if (!Number.isSafeInteger(v) || v < min) issues.push(`${name} must be an integer >= ${min}, got ${raw}`);
  };
  check('MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS', 1000);
  check('MASTRACODE_PROFILE_CAPTURE_INTERVAL_MS', 10000);
  check('MASTRACODE_PROFILE_ALLOCATION_INTERVAL_BYTES', 32768);
  return issues;
}

function isValidProfileInt(raw: string | undefined, min: number): raw is string {
  if (raw === undefined) return true;
  const v = Number(raw);
  return Number.isSafeInteger(v) && v >= min;
}

try {
  const setup = createProcessMemoryDiagnosticsFromEnvironment(env);
} catch (error) {
  if (error instanceof ProcessMemoryDiagnosticsConfigError) {
    console.error(`Bad profiling config: ${error.message}`);
  } else throw error;
}

When it happens

Trigger: Setting MASTRACODE_PROFILE_SAMPLE_INTERVAL_MS, MASTRACODE_PROFILE_CAPTURE_INTERVAL_MS, or MASTRACODE_PROFILE_ALLOCATION_INTERVAL_BYTES to a non-numeric string (e.g. '10s'), a non-integer ('0.5'), a value below its minimum (sample<1000, capture<10000, allocation<32768), or an interval above 2147483647; also an empty-ish non-blank string like ' '.

Common situations: Copy-pasting durations with units ('500ms'), using seconds instead of milliseconds ('10' intending 10s but minimum is 1000ms — actually valid, but '5' fails), typos, or CI env injection with quoted values like '"10000"'.

Related errors

• Auth0 domain and audience are required, please provide them
• 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
• Expected a PEM-encoded public key or certificate string for

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