Invalid OTEL_EXPORTER_PROMETHEUS_PORT

Error message

Invalid OTEL_EXPORTER_PROMETHEUS_PORT: '${configuredPort}'

What it means

prometheusPort parses the OTEL_EXPORTER_PROMETHEUS_PORT environment variable for the embedded Prometheus MetricReader. When set, the value must parse as an integer between 1 and 65535; otherwise the provider throws instead of silently falling back to the default port.

Solutions

Set OTEL_EXPORTER_PROMETHEUS_PORT to a plain integer between 1 and 65535 (e.g. 9464)
Remove the env var entirely to use DEFAULT_PROMETHEUS_PORT
Check for whitespace, quotes, or suffixes (e.g. '9464/tcp') in the value and strip them
Verify with `node -e "console.log(Number(process.env.OTEL_EXPORTER_PROMETHEUS_PORT))"` that the value parses as an integer

Example fix

// before
OTEL_EXPORTER_PROMETHEUS_PORT=http://localhost:9464
// after
OTEL_EXPORTER_PROMETHEUS_PORT=9464

Defensive patterns

Strategy: validation

Validate before calling

function isValidPort(v) { const n = Number(v); return Number.isInteger(n) && n >= 1 && n <= 65535; }

Type guard

function isValidPrometheusPort(v: unknown): v is number {
  const n = Number(v);
  return Number.isInteger(n) && n >= 1 && n <= 65535;
}

Try / catch

try {
  startTelemetry();
} catch (e) {
  if (String(e.message).startsWith('Invalid OTEL_EXPORTER_PROMETHEUS_PORT')) {
    console.error('Fix OTEL_EXPORTER_PROMETHEUS_PORT (integer 1-65535) or unset it');
    process.exit(1);
  }
  throw e;
}

Prevention

Store ports as bare integers in env files; never URLs or 'host:port' strings
Validate env vars at startup with a schema library (zod, envalid) before constructing providers
Document that unsetting the variable falls back to the default port
Watch for orchestrator templating that can leave literal '${VAR}' strings in values

When it happens

Trigger: Setting OTEL_EXPORTER_PROMETHEUS_PORT to a non-numeric string ('http'), a float ('8080.5'), 0, a negative number, a value above 65535, or a value with whitespace/suffix characters so Number() yields NaN or an out-of-range integer.

Common situations: Copy-pasting a full URL instead of a port into the env var; typos like '808o'; using port 0 expecting an ephemeral port; quoting issues in .env files adding stray characters; container orchestrator templates passing '${PORT}' literally.

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/fcc4b56a171b7e10. Report an issue: GitHub.

Appendix: source

Thrown at packages/mcp/src/lib/telemetry-provider.ts:19

import { metrics } from "@opentelemetry/api";
import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
import { RuntimeNodeInstrumentation } from "@opentelemetry/instrumentation-runtime-node";
import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
import { MeterProvider } from "@opentelemetry/sdk-metrics";
import { embeddedPrometheusIsEnabled } from "./telemetry-config.js";

const DEFAULT_PROMETHEUS_HOST = "127.0.0.1";
const DEFAULT_PROMETHEUS_PORT = 9464;

let embeddedRuntimeInstrumentation: RuntimeNodeInstrumentation | undefined;

function prometheusPort(environment: NodeJS.ProcessEnv): number {
  const configuredPort = environment.OTEL_EXPORTER_PROMETHEUS_PORT;
  if (!configuredPort) return DEFAULT_PROMETHEUS_PORT;

  const port = Number(configuredPort);
  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
    throw new Error(`Invalid OTEL_EXPORTER_PROMETHEUS_PORT: '${configuredPort}'`);
  }
  return port;
}

/**
 * Installs the embedded Prometheus MetricReader for HTTP serving. A provider
 * installed by an OpenTelemetry preload script wins, so no second SDK is
 * installed. This module is dynamically imported only when the embedded
 * exporter is enabled; stdio and SDK-disabled processes never load it.
 */
export async function startPrometheusMetrics(
  serviceVersion: string,
  environment: NodeJS.ProcessEnv = process.env
): Promise<MeterProvider | undefined> {
  if (!embeddedPrometheusIsEnabled(environment)) return undefined;

  let provider: MeterProvider | undefined;
  let providerWasRegistered = false;

View on GitHub (pinned to 4416fb855b)