Next.js return type for route handlers is overly restrictive

[billyjanitsch]

Link to the code that reproduces this issue

https://github.com/billyjanitsch/nextjs-typed-routes-bug

To Reproduce

1. Run npm install && npm test.
2. Note the typecheck error:

.next/types/validator.ts:25:11 - error TS1360: Type 'typeof import("/Users/billy/work/nextjs-typed-routes-bug/app/route")' does not satisfy the expected type 'RouteHandlerConfig<"/">'.
  The types returned by 'GET(...)' are incompatible between these types.
    Type 'Promise<Response | undefined>' is not assignable to type 'void | Response | Promise<Response> | Promise<void>'.
      Type 'Promise<Response | undefined>' is not assignable to type 'Promise<Response>'.
        Type 'Response | undefined' is not assignable to type 'Response'.
          Type 'undefined' is not assignable to type 'Response'.

25   handler satisfies RouteHandlerConfig<"/">

Current vs. Expected behavior

This route handler should pass typechecking:

export async function GET() {
  return Math.random() > 0.5 ? new Response() : undefined
}

Currently, it doesn't because Next.js's auto-generated type validation says:

type RouteHandlerConfig<Route extends AppRouteHandlerRoutes = AppRouteHandlerRoutes> = {
  GET?: (request: NextRequest, context: { params: Promise<ParamMap[Route]> }) => Promise<Response> | Response | Promise<void> | void
}

The problem is that Promise<Response | void> isn't assignable to Promise<Response> | Promise<void>.

The former should be a valid return type for route handlers. Can Next.js update its validation generator to replace Promise<Response> | Promise<void> with Promise<Response | void>?

Provide environment information

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 24.6.0: Mon Jul 14 11:30:30 PDT 2025; root:xnu-11417.140.69~1/RELEASE_ARM64_T6020
  Available memory (MB): 98304
  Available CPU cores: 12
Binaries:
  Node: 22.18.0
  npm: 11.5.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 15.5.0 // Latest available version is detected (15.5.0).
  eslint-config-next: 15.5.0
  react: 19.1.0
  react-dom: 19.1.0
  typescript: 5.9.2
Next.js Config:
  output: N/A

Which area(s) are affected? (Select all that apply)

Route Handlers, TypeScript

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local)

Additional context

No response

[jim-spr]

Big one!

[khalilsarwari]

After upgrading to 15.5, I get the error:

Type error: Type 'typeof import("/myapp/pages/api/test")' does not satisfy the expected type 'ApiRouteConfig'.
The types of 'config.api.responseLimit' are incompatible between these types.
Type 'boolean' is not assignable to type 'string | number | undefined'.
Next.js build worker exited with code: 1 and signal: null

When I do:

export const config = {
  api: {
    responseLimit: false,
  },
}

even though this is in the docs?

[jsa4000]

Hi,

My pipeline just failed trying to update to 15.5, i think it is the same problem.

Here is my error.

   Linting and checking validity of types ...
Failed to compile.

Type error: Type 'typeof import("/home/runner/work/saas-starter/saas-starter/apps/app/src/app/(dashboard)/dashboard/[[...plugins]]/layout")' does not satisfy the expected type 'LayoutConfig<"/dashboard/[[...plugins]]">'.
  Types of property 'default' are incompatible.
    Type '({ children, ...props }: LayoutProps) => Promise<Element>' is not assignable to type 'ComponentType<LayoutProps<"/dashboard/[[...plugins]]">> | ((props: LayoutProps<"/dashboard/[[...plugins]]">) => void | Promise<void> | ReactNode | Promise<...>)'.
      Type '({ children, ...props }: LayoutProps) => Promise<Element>' is not assignable to type 'FunctionComponent<LayoutProps<"/dashboard/[[...plugins]]">>'.
        Types of parameters '__0' and 'props' are incompatible.
          Type 'LayoutProps<"/dashboard/[[...plugins]]">' is not assignable to type 'LayoutProps'.
            Types of property 'params' are incompatible.
              Type 'Promise<{ plugins?: string[] | undefined; }>' is not assignable to type 'Promise<{ plugins: string[]; }>'.
                Type '{ plugins?: string[] | undefined; }' is not assignable to type '{ plugins: string[]; }'.
                  Types of property 'plugins' are incompatible.
                    Type 'string[] | undefined' is not assignable to type 'string[]'.
                      Type 'undefined' is not assignable to type 'string[]'.

Thanks a great work!

Regards,
Javier

[bgub]

@billyjanitsch, @jim-spr, @khalilsarwari, and @jsa4000 -- should be fixed now with 15.5.1-canary.1! Let me know if it doesn't solve the problem.