Invalid MCP_MAX_SUBSCRIPTIONS; using the default of

Error message

Invalid MCP_MAX_SUBSCRIPTIONS; using the default of ${DEFAULT_MAX_SUBSCRIPTIONS}.

What it means

getMaxSubscriptions parses MCP_MAX_SUBSCRIPTIONS; if the value is set but not a non-negative safe integer, it warns with this message and falls back to DEFAULT_MAX_SUBSCRIPTIONS. The process continues with the default rather than crashing.

Solutions

Set MCP_MAX_SUBSCRIPTIONS to a plain non-negative integer, e.g. MCP_MAX_SUBSCRIPTIONS=100.
Remove the variable entirely to use the default.
Check for hidden whitespace, quotes, or commas in the env definition.
Log the parsed value at startup to confirm the setting took effect.

Example fix

// before (in .env)
MCP_MAX_SUBSCRIPTIONS="1,000"
// after
MCP_MAX_SUBSCRIPTIONS=1000

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

const isValidMaxSubscriptions = (v: string): v is `${number}` => /^\d+$/.test(v.trim());

Prevention

Validate env vars at startup with a schema (e.g. zod).
Use plain integers without quotes, commas, or spaces in .env files.
Remove the variable rather than setting an empty string when you want the default.
Document the expected format next to where the value is configured.

When it happens

Trigger: Setting MCP_MAX_SUBSCRIPTIONS to a non-numeric string ("abc"), a negative number ("-1"), a float ("1.5"), Infinity/NaN forms, or a value beyond Number.MAX_SAFE_INTEGER, then starting the MCP server (rawMcpHandler / stdioHandle).

Common situations: Typo in the env value; quoting issues in .env files adding stray characters; copy-pasting a locale-formatted number like "1,000"; setting an empty string.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

AI-assisted analysis of upstash/context7@4416fb855b (2026-09-16). Data as JSON: /api/errors/99ed4936d2f7a6f6. Report an issue: GitHub.

Appendix: source

Thrown at packages/mcp/src/lib/subscriptions.ts:11

// Context7's tools, prompts, and resources are static for the process lifetime,
// so notification subscriptions provide no useful events.
export const DEFAULT_MAX_SUBSCRIPTIONS = 0;

export function getMaxSubscriptions(value = process.env.MCP_MAX_SUBSCRIPTIONS): number {
  if (value === undefined) return DEFAULT_MAX_SUBSCRIPTIONS;

  const parsed = Number(value);
  if (Number.isSafeInteger(parsed) && parsed >= 0) return parsed;

  console.warn(`Invalid MCP_MAX_SUBSCRIPTIONS; using the default of ${DEFAULT_MAX_SUBSCRIPTIONS}.`);
  return DEFAULT_MAX_SUBSCRIPTIONS;
}

View on GitHub (pinned to 4416fb855b)