remix-run/remix · error · Error

invalid bypass pattern ${JSON.stringify(pattern)}: path must

Error message

invalid bypass pattern ${JSON.stringify(pattern)}: path must start with "/"

What it means

This error is thrown by parseBypassPattern when a path portion of a bypass pattern passed to addInsecureBypassPattern does not begin with '/'. The cop-middleware matches request pathnames against registered bypass patterns, and a leading slash is required so patterns align with URL pathname semantics. Any pattern whose path segment lacks the leading slash is rejected immediately at registration time.

Source

Thrown at packages/cop-middleware/src/lib/cop.ts:245

    throw new Error('bypass pattern must not be empty')
  }

  let method: RequestMethod | null = null
  let pathname = trimmedPattern
  let methodPattern = /^([A-Z]+)\s+(.+)$/.exec(trimmedPattern)

  if (methodPattern != null && methodPattern[2].startsWith('/')) {
    let maybeMethod = methodPattern[1]
    if (!isRequestMethod(maybeMethod)) {
      throw new Error(`invalid request method in bypass pattern ${JSON.stringify(pattern)}`)
    }

    method = maybeMethod
    pathname = methodPattern[2]
  }

  if (!pathname.startsWith('/')) {
    throw new Error(`invalid bypass pattern ${JSON.stringify(pattern)}: path must start with "/"`)
  }

  if (pathname.includes('?') || pathname.includes('#')) {
    throw new Error(
      `invalid bypass pattern ${JSON.stringify(pattern)}: query strings and fragments are not supported`,
    )
  }

  let matchesSubtree = pathname.endsWith('/')
  let normalizedPathname =
    pathname.length > 1 && matchesSubtree ? pathname.slice(0, pathname.length - 1) : pathname
  let rawSegments = normalizedPathname === '/' ? [] : normalizedPathname.slice(1).split('/')
  let segments = rawSegments.map((segment, index) =>
    parseBypassSegment(pattern, segment, index === rawSegments.length - 1),
  )

  return { method, pathname, segments, matchesSubtree }
}

View on GitHub (pinned to 9696913134)

Solutions

Add a leading '/' to the path: addInsecureBypassPattern('GET /admin') instead of 'GET admin'
If using a method prefix, verify the format is 'METHOD /path' with the slash present
Double-check programmatically generated patterns prepend '/' before registration

Example fix

// before
cop.addInsecureBypassPattern('GET admin/*')
// after
cop.addInsecureBypassPattern('GET /admin/*')

Defensive patterns

Strategy: validation

Validate before calling

function assertBypassPath(pattern: string) {
  const path = pattern.includes(' ') ? pattern.slice(pattern.indexOf(' ') + 1) : pattern
  if (!path.startsWith('/')) throw new Error(`pattern path must start with '/': ${pattern}`)
}
assertBypassPath('GET /admin')

Type guard

function hasValidBypassPath(pattern: string): boolean {
  const path = pattern.includes(' ') ? pattern.slice(pattern.indexOf(' ') + 1).trim() : pattern
  return path.startsWith('/')
}

Try / catch

try { cop.addInsecureBypassPattern(p) } catch (e) { if (e instanceof Error && e.message.includes('path must start with')) { /* log config error, fix pattern */ } throw e }

Prevention

Centralize bypass patterns in one config module with tests
Write a startup validator that checks every pattern's path prefix before registration

When it happens

Trigger: Calling addInsecureBypassPattern('GET admin/*') or addInsecureBypassPattern({ method: 'POST', path: 'api/public' }) — any pattern whose path part does not start with '/'. Also occurs when a pattern string like 'GET /admin' is mis-parsed so the method consumes the slash, or the path is an empty string.

Common situations: Copy-pasting route paths from a router config that omits leading slashes; passing a Windows-style or relative path; forgetting the slash after an HTTP method prefix ('GET admin' instead of 'GET /admin').

Related errors

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