ky has conflicts with Next.js App Router

[Euruson]

Thanks for this excellent repo! I’m currently building my blog using Next.js with the App Router.

I ran into an issue where notion-client (specifically ky) fails to fetch data during build time—such as when using getCollectionData() inside a sitemap route or within a generateStaticParams() function. The request seems to hang indefinitely without returning data or throwing an error, and the browser page just keeps loading.

As a quick test, I replaced ky with the native fetch() API in notion-client, and the issue was resolved.

I’m not entirely sure why this happens—it might be related to how Next.js handles caching or fetch contexts during static generation. I’m also curious about the choice of ky in the codebase. Are there specific advanced features from ky that are being used?

[transitive-bullshit]

thanks, @Euruson.

i'm mainly using ky because of the built-in retry logic, since notion's unofficial api is sometimes flaky.

i'll take another look at #646

[likerRr]

👋
Confirming the issue: build stucks on fetching data within generateStaticParams using the app router

[likerRr]

I think I've found the issue. It's because of the mode: no-cors.

I dove into the debug session and caught this error from the ky's request:

TypeError: If request is made from ReadableStream, mode should be "same-origin" or "cors"
    at X (.next/server/chunks/985.js:1:22386)
    at <unknown> (.next/server/chunks/985.js:1:25919)
    at <unknown> (.next/server/chunks/985.js:19:5117)
    at e.with (.next/server/chunks/985.js:22:12924)
    at i.with (.next/server/chunks/985.js:22:7171)
    at i.startActiveSpan (.next/server/chunks/985.js:22:22137)
    at e.startActiveSpan (.next/server/chunks/985.js:22:22671)
    at <unknown> (.next/server/chunks/985.js:19:4625)
    at e.with (.next/server/chunks/985.js:22:12924)

@transitive-bullshit So I'm not sure that #646 will fix this issue, cause it's related to how Next.js processes requests in app router mode – it simply can't read the response, cause it's an opaque – and that's why it forbids mode: no-cors on fetch, I guess.

@Euruson as a solution (not sure if it's temporal or permanent) I may suggest you to update the mode manually, anyway cors doesn't make any sense if the requests are made not from a browser:

export const notionApi = new NotionAPI({
  kyOptions: {
    mode: 'cors',
  },
});

It works, at least :)

[likerRr]

TL;DR

1. This PR added no-cors, but that's not appropriate here: no-cors means "ignore the response", while we need the response from Notion API.
2. Avoid using Request object (like ky does) with no-cors, because behavior differs between environments (Node, browser, Next.js app router).
3. Correct solution to the issue: remove mode: "no-cors". Notion API requests must be made from server-side Node.js runtime, where CORS is irrelevant.

P.S. Sorry for the long, but detailed post 🫶

---

Oh my, guys, I was a bit wrong. And there are, actually, several questions that need to be answered to understand the issue:

1. Why replacing ky with fetch works?
2. Why the starter kit works well with Nextjs pages router?
3. Why notion-client works with static pages, but throws the error in generated pages (Nextjs app router)?

Let's begin with fetch vs Request

We have basically two ways to make a request:

fetch(url, options);

or

fetch(new Request(url, options))

And they are not exactly the same.

1. According to the WHATWG spec, when you create a Request with a string body, the constructor goes through the "extract a body" algorithm. That associates the request with a body backed by a stream (ReadableStream).
2. But when you pass body directly to fetch(url, { body: "…" }), the spec says:

A request has an associated body (null, a byte sequence, or a body).

In this case, the body stays as a byte sequence (not immediately wrapped into a stream).

This difference matters because you cannot use mode: "no-cors" with a ReadableStream body. The spec explicitly disallows it.

About no-cors

no-cors does not mean "bypass CORS". It means:

• The request is sent, but the response is opaque and cannot be read.
• Headers/methods are restricted to "simple requests". For example, Content-Type: application/json is silently downgraded to text/plain;charset=UTF-8.
• This mode is meant for cases where the client doesn't care about the response (analytics beacons, logging, preloading assets into cache, etc.).

In our case we do care about the response, so no-cors is not suitable.

Node.js vs Browser

CORS is a browser mechanism. Node.js's fetch implementation (via undici) doesn't enforce these restrictions strictly:

• Passing a string body into new Request() does not trigger the same checks as in browsers.
• That's why in Node.js we don't see the ReadableStream + no-cors error.

Next.js pages router vs app router

• In the pages router (getStaticPaths etc.), everything runs on Node.js runtime with Node's own fetch implementation. That's why no error.

• In the app router, generateStaticParams and other server functions also run on Node.js, but Next.js wraps fetch to add features (RSC caching, deduplication, etc.). This wrapper follows the spec more strictly, closer to browsers (to behave the way as these components were rendered in browser). That's why wee see the no-cors + Request error there. And this is an assumption here, because I didn't dig into Next.js's internal, but all the evidences point to this. Even if I'm wrong, it doesn't actually change anything in terms of this issue.

Now with all the info in mind, I can answer all the initial questions:

1. Why replacing ky with fetch works?
   Because ky internally creates a Request object with mode: "no-cors" provided by notion-client, that triggers the ReadableStream restriction. Calling fetch(url, { ... }) directly avoids this.

2. Why does the starter kit work with pages router?
   Because pages router functions (getStaticPaths, getStaticProps) use Node's fetch, which doesn't enforce no-cors restrictions.

3. Why does notion-client work in static pages but throws in generated pages (app router)?
   Because app router uses browser-spec driven fetch wrapper. It enforces the no-cors + ReadableStream restriction (despite it runs in Node.js), causing the error when you construct Request manually.

---

I've also created a simple test for the error reproduction

Generate a basic Next.js app with App Router. Create a dynamic route segment, e.g. /app/[pageId]/page.tsx, and try to build this:

// This WILL NOT THROW the error

export async function generateStaticParams() {
  await fetch('https://www.notion.so/api/v3/loadPageChunk', {
    mode: 'no-cors',
    method: 'POST',
    body: JSON.stringify({
      pageId: 'PAGE_ID', // <======= replace with yours
      limit: 100,
      chunkNumber: 0,
      cursor: { stack: [] },
      verticalColumns: false,
    }),
    headers: { 'Content-Type': 'application/json' },
  });
}

export default function Page() {
  return null
}

vs

// The same request, constructed with Request, but it WILL THROW the error

export async function generateStaticParams() {
  const request = new Request('https://www.notion.so/api/v3/loadPageChunk', {
    mode: 'no-cors',
    method: 'POST',
    body: JSON.stringify({
      pageId: 'PAGE_ID', // replace with yours
      limit: 100,
      chunkNumber: 0,
      cursor: { stack: [] },
      verticalColumns: false,
    }),
    headers: { 'Content-Type': 'application/json' },
  });

  await fetch(request);
}

export default function Page() {
  return null
}

[Euruson]

@likerRr Thanks a lot for your thorough investigation #657 (comment) into this issue. I have learned a lot.

While I followed most of your answers to the key questions, I’m still unclear on one point: Why does notion-client work in static pages but fail in generated pages (App Router)?

You mentioned that the App Router uses a browser-spec–driven fetch wrapper. But since the browser also follows the same specs—and also uses no-cors and ReadableStream—why doesn’t it encounter the same problem?

[likerRr]

@Euruson yeah, that's a good question. From my observation I would say, that the app router works differently for the named and segmented routes. The issue reproduces only for the segmented routes. Here I just can assume, this is either a bug in Next.js or by design (but I have no explanation why).

Thus for the named routes (app/page.tsx) Next.js uses Node's fetch implementation, but for the segmented (/app/[pageId]/page.tsx) routes it [seems like] uses Browser-compliant fetch, causing no-cors issues

[Euruson]

@likerRr Thanks for your answer, where I learned the different fetch behaviors of Next.js APP Router.

Sorry for my confusing question. What I really mean is that whethernotion-client works fine in static pages in the browser env / client side, like SPA or vanilla JS. It constructs fetch requests with no-cors + ReadableStream, and it should follow the browser spec. Will it also throw errors? If so, I think we get to the root of this problem. And it's understandable that Next.js wants to keep the fetching behavior the same across different platforms.

[likerRr]

@Euruson sorry for the long reply, but your great questions made me dive into this issue again, but now straight to the Next.js/Node docs/source code :)

Here, what I've found, and now I think this finally explains everything.

We already know that ky constructs fetch by passing a Request object as its argument:

// https://github.com/sindresorhus/ky/blob/17ca3894b5f2b1957f7255bd8a805b3f68e5e17c/source/core/Ky.ts#L188
this.request = new globalThis.Request(this._input, this._options);

// https://github.com/sindresorhus/ky/blob/17ca3894b5f2b1957f7255bd8a805b3f68e5e17c/source/core/Ky.ts#L326
const mainRequest = this.request;
this._options.fetch(mainRequest, nonRequestOptions);

What happens with the body, when it's wrapped with Request? It transforms into a ReadableStream:

const req = new Request('url', {
  method: 'POST',
  body: JSON.stringify({}), // here body is a string
})

console.log(req.body) // here body is already a ReadableStream, that's by spec

The Request constructor

You can test the example above yourself right in a dev console (doesn't matter node or browser), but I'll walk through the source code of the undici (it's a whatwg-compliant fetch implementation used by browsers and node), specifically of the Request class constructor to cover the key points:

1. body extraction
2. conversion to ReadableStream
3. returning the extracted body as an object with: source (a string in case of JSON body), stream (a ReadableStream), length (not important) properties
4. if (inputOrInitBody != null && inputOrInitBody.source == null) { – this condition is skipped, because inputOrInitBody.source is not null (it's a string from the previous step). But this condition is the only place, which can through our error. I will come back to it later.
5. the extracted body from the p.3 is assigned to a finalBody: let finalBody = inputOrInitBody
6. then finalBody is assigned to a private body property of the Request instance: this.#state.body = finalBody
7. and now we can clearly see why req.body always returns a ReadableStream (stream variable from the p.3):
   return this.#state.body ? this.#state.body.stream : null

Taking how this work into account, I can already reproduce our error in a bare minimal environment, and no fetch is even required!

const req = new Request('url', {
  method: 'POST',
  mode: 'no-cors',
  body: JSON.stringify({}), // here body is a string
})

new Request('url', req);

Now this code throws (just check yourself in the browser console):

Uncaught TypeError: Failed to construct 'Request': If request is made from ReadableStream, mode should be"same-origin" or "cors"

Let's figure out, why it happens by reviewing new Request('url', req); over the 7 steps of Request constructor I described above.

1. there is a body extraction algorithm, which accepts init.body. But what is the init.body in this case? It's a req.body – which is already a ReadableStream (see p.7 above):

// this is the expanded version of the "new Request('url', req)"

const req = new Request('url', { ... })

new Request('url', {
  method: req.method,
  mode: req.mode,
  body: req.body, // the body is a ReadableStream!!
})

2. conversion does not occur, since it's already a ReadableStream, so the stream remains a ReadableStream
3. the extracted body now consists of a source = null (because the object doesn't pass any of the conditions started from the line 93)
4. Since source now is null, it falls into the condition if (inputOrInitBody != null && inputOrInitBody.source == null) {, which finally causes our error!

The nature of the error is now clear. But you may ask: "Man, this is cool, but why you explaining this strange use case of wrapping one Request into another? We don't do this anywhere in NotionX or in our client code, we are not fools!".

And you're right, but Next.js does this 😢

How Next.js breaks our Request

Well, that's another story. Next.js uses different scripts to build the App Router and the Pages Router.

And Next.js patches the fetch function and later calls it only for the App Router. That's why we don't see any issues with the starter-kit which is built using the Pages Router.

If we look at the source code of createPatchedFetcher function, we can see this:

// ...
  // reqOptions here is our initial Request instance where the `body` property is already converted to a ReadableStream
  input = new Request(reqInput.url, reqOptions) 
  // ... 
  const clonedInit = {
    ...init,
    // ...
  }

return originFetch(input, clonedInit)

This is where the wrapping of our original Request (which ky builds) happens. And this is exactly why we see the error.

Why there are no errors if we call fetch right inside the App Router's async components?

For the App Router (inside the patched fetch) Next.js also handles an incremental cache. When some conditions are met, it calls the generateCacheKey method, which adds to our request object a new property – _ogBody which is an ArrayBuffer converted from our ReadableStream 😅. And the [non-intended] trick is, that when there is an _ogBody in the request options, it has higher priority over the original body (which is ReadableStream in our case). So in fact, it converts our ReadableStream body from the initial Request to the ArrayBuffer and then this ArrayBuffer is used as a body of reqOptions. On top of that the ArrayBuffer plays absolutely nice with the mode: no-cors, thus not causing any errors.

But that's still not the end. The incremental cache by default is enabled only for the named routes. So for the segmented routes, even if they don't define generateStaticParams(), the incremental cache for the fetch is skipped (both conditions are false), so no _ogBody is added, and this causes the already known error.

This is absolutely crazy, to be honest – a very doubtful design decision by the Next.js. Despite the case is super rare, they just break the client code by patching the fetch hardly, what brings unexpected behavior. The debug becomes quite difficult and time consuming, and the developer experience (at least mine) is absolutely ruined.

Still, the solution of removing mode: no-cors from the notion-client is the only right for the topic of the issue. The App Router just adds more noise on top of that.

[Euruson]

@likerRr Thanks much for such a deep investigation. The cache mechanism of Next.js APP Router is really messy and unpredictable across platforms,  which is the root of the inconsistency we’re seeing.

@transitive-bullshit I think @likerRr provides a reliable resolution and is better than replacing ky with got provided in #646.

[likerRr]

I've additionally raised an issue on the Next.js's repo, so we can have some comments from the team.