remix-run/remix · error · TypeError

${optionPath} must use version components between 0 and 255

Error message

${optionPath} must use version components between 0 and 255

What it means

Thrown when a browser target version has a component greater than 255. Versions are packed into a compact numeric representation, so each of the up-to-three components must fit in one byte (0–255). Values like '300' or '90.999' pass the format check but exceed the component limit.

Source

Thrown at packages/assets/src/lib/target.ts:183

  return `es${normalizedValue}`
}

function normalizeBrowserTargetVersion(value: unknown, optionPath: string): AssetTargetVersion {
  if (typeof value !== 'string') {
    throw new TypeError(`${optionPath} must be a string`)
  }

  if (value.trim().length === 0) {
    throw new TypeError(`${optionPath} must be a non-empty string`)
  }

  if (!/^\d+(\.\d+){0,2}$/.test(value)) {
    throw new TypeError(`${optionPath} must use "X", "X.Y", or "X.Y.Z" version format`)
  }

  let segments = value.split('.').map(Number)
  if (segments.some((segment) => segment > 255)) {
    throw new TypeError(`${optionPath} must use version components between 0 and 255`)
  }

  return value as AssetTargetVersion
}

function toLightningCssTargetVersion(version: AssetTargetVersion): number {
  let [major, minor = 0, patch = 0] = version.split('.').map(Number)
  return major * 65536 + minor * 256 + patch
}

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value)
}

View on GitHub (pinned to 9696913134)

Solutions

1. Correct the version to a plausible browser release (all current browsers are well under 255)
2. Sanity-check generated config: reject components > 255 before calling the assets API
3. If the value came from a User-Agent parse, verify you extracted the browser version, not a build/patch number

Example fix

// before
let target = { script: { chrome: '3000' } }
// after
let target = { script: { chrome: '90' } }

let isValidVersion = (value: string) =>
  /^\d+(\.\d+){0,2}$/.test(value) && value.split('.').every((s) => Number(s) <= 255)
if (!isValidVersion(version)) throw new Error('version components must be 0-255')

let isByteVersion = (value: unknown): value is string =>
  typeof value === 'string' &&
  /^\d+(\.\d+){0,2}$/.test(value) &&
  value.split('.').every((s) => Number(s) <= 255)

When it happens

Trigger: `{ script: { chrome: '300' } }`, `{ style: { safari: '16.999' } }`, or any component numerically above 255 even if well-formatted.

Common situations: Typos (extra digit) in version numbers; future-dated or nonsense versions from generated config; copying build numbers like '1234' into a version field.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• basePath must be a string
• fingerprint.buildId must be a string
• fingerprint.buildId must be a non-empty string
• files.extensions must be an array
• files.extensions values must be strings

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/e84158d3bb375f35. Report an issue: GitHub.