moeru-ai/airi · error · Error

Invalid remote debug port: ${env.APP_REMOTE_DEBUG_PORT}

Error message

Invalid remote debug port: ${env.APP_REMOTE_DEBUG_PORT}

What it means

Thrown by setupDebugger in the Electron main process when APP_REMOTE_DEBUG is truthy but APP_REMOTE_DEBUG_PORT cannot be parsed as a valid integer port (0–65535). The validator uses Number(env.APP_REMOTE_DEBUG_PORT || '9222'), so an empty value falls back to 9222 safely; the throw only happens for a non-empty, malformed, or out-of-range value.

Source

Thrown at apps/stage-tamagotchi/src/main/app/debugger.ts:12

import http from 'node:http'

import { env } from 'node:process'

import { app, shell } from 'electron'

/** Enables Electron's CDP endpoint before the app ready event. */
export function setupDebugger() {
  if (/^true$/i.test(env.APP_REMOTE_DEBUG || '')) {
    const remoteDebugPort = Number(env.APP_REMOTE_DEBUG_PORT || '9222')
    if (Number.isNaN(remoteDebugPort) || !Number.isInteger(remoteDebugPort) || remoteDebugPort < 0 || remoteDebugPort > 65535) {
      throw new Error(`Invalid remote debug port: ${env.APP_REMOTE_DEBUG_PORT}`)
    }

    app.commandLine.appendSwitch('remote-debugging-port', String(remoteDebugPort))
    app.commandLine.appendSwitch('remote-allow-origins', `http://localhost:${remoteDebugPort}`)
  }
}

/**
 * Opens the inspector for the first available Electron renderer target.
 *
 * Developers may keep CDP enabled without opening the system browser by
 * setting `APP_REMOTE_DEBUG_NO_OPEN=true`.
 */
export function openDebugger() {
  if (/^true$/i.test(env.APP_REMOTE_DEBUG || '')) {
    const remoteDebugEndpoint = `http://localhost:${env.APP_REMOTE_DEBUG_PORT || '9222'}`

    http.get(`${remoteDebugEndpoint}/json`, (res) => {

View on GitHub (pinned to 27111382b4)

Solutions

1. Set APP_REMOTE_DEBUG_PORT to an integer between 0 and 65535 (commonly 9222).
2. Omit APP_REMOTE_DEBUG_PORT entirely to accept the 9222 default.
3. If you do not need remote debugging, leave APP_REMOTE_DEBUG unset/false so the validator never runs.
4. Check the launch profile / package.json script that sets the env var for stray characters.

Example fix

// before
APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=92:22 electron .

// after
APP_REMOTE_DEBUG=true APP_REMOTE_DEBUG_PORT=9222 electron .

function parseDebugPort(raw: string | undefined): number | null {
  const port = Number(raw || '9222')
  if (Number.isNaN(port) || !Number.isInteger(port) || port < 0 || port > 65535) return null
  return port
}

if (parseDebugPort(env.APP_REMOTE_DEBUG_PORT) === null) {
  // fail with a clear message before Electron app construction
}

function isValidPort(raw: string | undefined): boolean {
  const port = Number(raw || '9222')
  return Number.isInteger(port) && port >= 0 && port <= 65535
}

When it happens

Trigger: Launching the Electron app with APP_REMOTE_DEBUG=true and APP_REMOTE_DEBUG_PORT set to a non-numeric string (e.g. 'abc'), a float (e.g. '9222.5'), a negative number, or a value above 65535.

Common situations: Typo in an .env or launch config; copy-pasting a port string with a colon; setting a port already expressed as a URL fragment; CI matrix setting an out-of-range port variable.

Related errors

• GODOT4 is required to start Godot Stage in development mode.
• No reachable private LAN address is available for the curren
• Failed to apply server channel configuration
• GODOT4 points to a missing Godot executable.\nConfigured pat
• GODOT4 must point to the Godot executable file, not a direct

AI-assisted analysis of moeru-ai/airi@27111382b4 (2026-08-12). Data as JSON: /api/errors/14e65e5c89163e5f. Report an issue: GitHub.