Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

TypeError: Failed to parse URL when a Next.js server fetches its own API

ErrorTypeError: Failed to parse URL from /api/test

Short answer

Server code has no page address, so fetch('/api/test') cannot be turned into a full URL and throws Failed to parse URL. Give fetch an absolute URL, make sure the variable that builds it is not undefined, or skip the HTTP call and run the same logic directly from the Server Component.

  • Applies to Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the exact string passed to fetch. The text after 'from' in the error is that string, and its shape decides the cause.

    grep -rnE "fetch\(" app lib pages | grep -v node_modules
  2. 2Match what you see, then jump to its fix

    1. 1The error says Failed to parse URL from /api/test, a bare pathA path without a host is used in server codeFix
    2. 2The error shows undefined/api/test, or the host part is missingThe environment variable that holds the base URL is emptyFix
    3. 3The page fetches /api/... from the same appA Server Component calls its own API routeFix

What does the error look like?

  • TypeError: Failed to parse URL from /api/test
  • TypeError: Failed to parse URL from undefined/api/test

Cause 1 of 3

A path without a host is used in server code

1Check

A relative reference only resolves in the browser, against the page address. Without a base, the URL parser throws a TypeError.

node -e "try { new URL('/api/test') } catch (e) { console.log(e.name) }"

2Fix

Build an absolute URL, or pass a base explicitly.

const url = new URL('/api/test', 'https://example.com')
const res = await fetch(url)

3Verify

Reload the page; the server log no longer prints the error.

curl -I https://example.com/api/test

Confirmed by developer.mozilla.org

Did this fix it?

Cause 2 of 3

The environment variable that holds the base URL is empty

1Check

A template string such as `${process.env.API_URL}/api/test` turns into undefined/api/test when the variable is absent. Next.js loads .env files at startup, so a new variable needs a restart, and a server-only variable is not visible to the browser unless it starts with NEXT_PUBLIC_.

grep -n "API_URL" .env .env.local 2>/dev/null

2Fix

Define the variable in the right .env file, restart the server, and use NEXT_PUBLIC_ only where the browser needs it.

# .env.local
API_URL=http://localhost:3000

3Verify

Log the value once on the server after the restart.

node -e "console.log(require('fs').readFileSync('.env.local','utf8'))"

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

A Server Component calls its own API route

1Check

Server Components can read data directly, with fetch or a database client, so an HTTP hop to your own route only adds a URL that can be wrong.

grep -rn "/api/" app --include=page.tsx --include=page.js

2Fix

Move the data logic into a shared function and call it from both the route handler and the Server Component.

// lib/items.ts
export async function getItems() {
  return db.select().from(items)
}

// app/items/page.tsx
import { getItems } from '@/lib/items'
export default async function Page() {
  const items = await getItems()
  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>
}

3Verify

Reload the page; it renders without any request to your own /api route.

npm run dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Never write fetch('/api/...') in a Server Component, a route handler or a Server Action.
  • Keep one base URL variable per environment and check it at startup.
  • Share data functions between pages and route handlers instead of calling your own endpoints.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.