paperclipai/paperclip · critical · Error

Invalid port: ${raw}

Error message

Invalid port: ${raw}

What it means

parsePort in the kv-demo MCP server config accepts string or number and requires the result to be an integer in [0, 65535]; anything else throws. An empty/null/undefined value is allowed and defaults to 8848, so the error only fires on a present-but-invalid value.

Source

Thrown at packages/kv-demo-mcp-server/src/config.ts:18

export interface KvDemoConfig {
  port: number;
  host: string;
  /** Optional shared secret. When set, all routes require it. */
  token: string | null;
}

export interface KvDemoConfigInput {
  port?: string | number | null;
  host?: string | null;
  token?: string | null;
}

function parsePort(raw: string | number | null | undefined): number {
  if (raw === null || raw === undefined || raw === "") return 8848;
  const port = typeof raw === "number" ? raw : Number.parseInt(raw, 10);
  if (!Number.isInteger(port) || port < 0 || port > 65535) {
    throw new Error(`Invalid port: ${raw}`);
  }
  return port;
}

export function createKvDemoConfig(input: KvDemoConfigInput): KvDemoConfig {
  const token = input.token?.trim();
  return {
    port: parsePort(input.port),
    host: input.host?.trim() || "127.0.0.1",
    token: token ? token : null,
  };
}

export function readConfigFromEnv(env: NodeJS.ProcessEnv = process.env): KvDemoConfig {
  return createKvDemoConfig({
    port: env.PORT ?? env.KV_DEMO_PORT,
    host: env.KV_DEMO_HOST,
    token: env.KV_DEMO_TOKEN,

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Set the port to an integer between 0 and 65535 (e.g. KV_PORT=8848).
2. Unset the port variable to fall back to the default 8848.
3. Strip any non-digit characters from the configured value before passing it in.

Example fix

// before
createKvDemoConfig({ port: '8848/tcp' })  // -> Invalid port: 8848/tcp
// after
createKvDemoConfig({ port: 8848 })

function validPort(raw: string|number|null|undefined): boolean {
  if (raw === null || raw === undefined || raw === '') return true;
  const n = typeof raw === 'number' ? raw : Number.parseInt(String(raw), 10);
  return Number.isInteger(n) && n >= 0 && n <= 65535 && String(raw).match(/^[0-9]+$/) !== null;
}

When it happens

Trigger: KvDemoConfigInput.port is a non-numeric string ('abc'), a float (8848.5), a number outside 0–65535 (70000, -1), or a string with garbage ('8848/tcp'). Number.parseInt on a float string like '8080' works, but '80.5' yields 80 — note partial parse quirks.

Common situations: KV_PORT env var set to a value with a unit suffix, a quoted float, or a port duplicated by mistake (80808080); mis-typed config in a YAML/JSON file read as a string.

Related errors

• Sandbox callback bridge did not report a listening port.
• OpenCode requires `adapterConfig.model` in provider/model fo
• Pi requires `adapterConfig.model` in provider/model format.
• --payload must be a JSON object
• ${name} must be a JSON object

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/733c57c4ed1a0af9. Report an issue: GitHub.