parcel-bundler/parcel · error · Error

Port ${portValue} is not a valid integer.

Error message

Port ${portValue} is not a valid integer.

What it means

Thrown by parsePort() when the --port CLI argument cannot be parsed as an integer. The function uses Number(portValue) then checks Number.isInteger(). This catches floats (e.g., '1234.5'), non-numeric strings (e.g., 'abc'), empty strings, and special values like NaN/Infinity. Note: integer strings like '8080' pass correctly.

Source

Thrown at packages/core/parcel/src/cli.js:417

    } catch (err) {
      // If an exception is thrown during Parcel.build, it is given to reporters in a
      // buildFailure event, and has been shown to the user.
      if (!(err instanceof BuildError)) {
        await logUncaughtError(err);
      }
      await exit(1);
    }

    await exit();
  }
}

function parsePort(portValue: string): number {
  let parsedPort = Number(portValue);

  // Throw an error if port value is invalid...
  if (!Number.isInteger(parsedPort)) {
    throw new Error(`Port ${portValue} is not a valid integer.`);
  }

  return parsedPort;
}

function parseOptionInt(value) {
  const parsedValue = parseInt(value, 10);
  if (isNaN(parsedValue)) {
    throw new commander.InvalidOptionArgumentError('Must be an integer.');
  }
  return parsedValue;
}

async function normalizeOptions(
  command,
  inputFS,
): Promise<InitialParcelOptions> {
  let nodeEnv;

View on GitHub (pinned to 59484858a1)

Solutions

1. Provide a valid integer port number: `--port 3000`.
2. If using an environment variable, ensure it's set and numeric: `--port $PORT` where PORT=3000.
3. Remove the --port flag to use the default port 1234.
4. Validate before passing: `[[ "$PORT" =~ ^[0-9]+$ ]] && parcel serve --port $PORT`.

Example fix

// before
$ parcel serve --port 8080.5
// Error: Port 8080.5 is not a valid integer.

// after
$ parcel serve --port 8080

// Validate port before passing to Parcel CLI
function validatePort(portStr) {
  let parsed = Number(portStr);
  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
    throw new Error(`Invalid port: ${portStr}. Must be an integer 0-65535.`);
  }
  return parsed;
}

// In a script:
const port = validatePort(process.env.PORT || '3000');

When it happens

Trigger: Running `parcel serve --port abc`, `parcel serve --port 8080.5`, or `parcel serve --port ''`. parsePort receives the raw string from commander, calls Number() on it, and Number.isInteger() returns false for any non-integer result. The default port ('1234') is used when no --port is provided and always passes.

Common situations: Passing a hostname or URL as the port by mistake. Using a float port number. Empty string from an environment variable expansion that resolves to nothing. Shell quoting issues passing an unexpected value. Port range notation like '3000-3010' (Parcel doesn't support ranges).

Related errors

• Feature flag ${name} must be set to true or false
• Could not get available port: ${err.message}
• Port "${originalPort}" could not be used
• Entry ${entry} does not exist
• Targets option is an empty array

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/e41129fa73922000. Report an issue: GitHub.