What causes "Request URL is missing." in payloadcms/payload?

Always reach the endpoint over HTTP via the registered route rather than calling the handler programmatically.

payloadcms/payload · error · APIError

Request URL is missing.

Error message

Request URL is missing.

What it means

APIError (HTTP 400, 'Request URL is missing.') thrown when req.url is falsy at the point of building search params. This is a framework-level precondition: the Hono/express request must carry a URL so that `new URL(req.url)` can parse query string.

Source

Thrown at packages/payload/src/uploads/endpoints/getFileFromURL.ts:45

    throw new APIError('Pasting from URL is not enabled for this collection.', 400)
  }

  if (id) {
    // updating doc
    const accessResult = await executeAccess({ slug: config.slug, req }, config.access.update)
    if (!accessResult) {
      throw new Forbidden(req.t)
    }
  } else {
    // creating doc
    const accessResult = await executeAccess({ slug: config.slug, req }, config.access?.create)
    if (!accessResult) {
      throw new Forbidden(req.t)
    }
  }

  if (!req.url) {
    throw new APIError('Request URL is missing.', 400)
  }

  const { searchParams } = new URL(req.url)
  const src = searchParams.get('src')

  if (!src || typeof src !== 'string') {
    throw new APIError('A valid URL string is required.', 400)
  }

  const hasAllowList =
    typeof config.upload.pasteURL === 'object' && Array.isArray(config.upload.pasteURL.allowList)

  let fileURL: string
  try {
    fileURL = new URL(src).href
  } catch {
    throw new APIError('A valid URL string is required.', 400)
  }

View on GitHub (pinned to 00c58b35c0)

Solutions

Always reach the endpoint over HTTP via the registered route rather than calling the handler programmatically.
In tests, build a PayloadRequest with a populated url (including the ?src= query).
If invoking internally, synthesize req: { url: '/api/.../paste-url?src=...', ... }.
Inspect any middleware that may be clearing req.url before the handler.

Example fix

// test — before
const res = await getFileFromURLHandler({ user, payload } as any)
// after — include url
const res = await getFileFromURLHandler({
  user, payload,
  url: '/api/media/paste-url?src=https://cdn.example.com/x.png',
  searchParams: new URLSearchParams({ src: 'https://cdn.example.com/x.png' }),
} as any)

Defensive patterns

Strategy: validation

Validate before calling

function requestHasUrl(req: { url?: string }): boolean {
  return typeof req?.url === 'string' && req.url.length > 0
}
// in tests:
if (!requestHasUrl(mockReq)) throw new Error('Test req missing url')

Type guard

const hasUrl = (req: { url?: string }): req is { url: string } =>
  typeof req?.url === 'string' && req.url.length > 0

Try / catch

try {
  await getFileFromURLHandler(req)
} catch (e) {
  if (/Request URL is missing/.test(e.message)) throw new Error('Programming error: handler called without req.url')
}

Prevention

Always invoke the handler through the registered HTTP route.
In tests, build a complete PayloadRequest including url + searchParams.
Avoid middleware that strips req.url.
Document the handler's precondition that req.url be set.

When it happens

Trigger: The handler is invoked through a code path that didn't set req.url (e.g. a programmatic/internal call, a custom endpoint wrapper, or a misrouted request). In normal HTTP traffic this essentially never fires.

Common situations: Calling the handler directly from server code without a synthesized PayloadRequest; a test harness building an incomplete req object; an exotic proxy stripping the request line; middleware that nulls req.url.

Related errors

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/14f11999b00d272d. Report an issue: GitHub.