nextjs routing_error ai_generated true

Error: Conflicting route found. The route at '/api/X' already exists.

ID: nextjs/route-conflict

Also available as: JSON · Markdown
92%Fix Rate
93%Confidence
80Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
14 active — — —

Root Cause

Two or more route definitions resolve to the same URL path. This commonly occurs when both App Router (app/) and Pages Router (pages/) define the same route, or when route groups and parallel routes create overlapping paths.

generic

Workarounds

  1. 95% success Remove the duplicate route from either pages/ or app/ directory 
    # Identify conflicting files:
# app/api/users/route.ts  <-- App Router route
# pages/api/users.ts      <-- Pages Router route
# Delete one of them. Prefer keeping the App Router version:
rm pages/api/users.ts

    Sources: https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration#migrating-from-pages-to-app

  2. 90% success Use route groups with distinct paths to separate overlapping route logic 
    # Instead of two conflicting routes:
# app/(marketing)/about/page.tsx
# app/(shop)/about/page.tsx
# Restructure to avoid the same path:
# app/(marketing)/about/page.tsx
# app/(shop)/shop-about/page.tsx
# Or consolidate into a single page with conditional logic

    Sources: https://nextjs.org/docs/app/building-your-application/routing/route-groups

  3. 93% success Consolidate duplicate API route handlers into a single route.ts with multiple method exports 
    // app/api/users/route.ts
// Combine all HTTP methods in one file:
export async function GET(request: Request) {
  // handle GET
}

export async function POST(request: Request) {
  // handle POST
}

export async function DELETE(request: Request) {
  // handle DELETE
}

    Sources: https://nextjs.org/docs/app/building-your-application/routing/route-handlers#supported-http-methods

Dead Ends

Common approaches that don't work:

  1. Delete the .next build cache and rebuild 95% fail

    The conflict exists in the source code file structure, not in the build cache. Clearing .next will not resolve duplicate route definitions. The error will reappear on the next build.

  2. Rename one route to use a different HTTP method to differentiate them 90% fail

    Route conflicts are path-based, not method-based. In the App Router, a single route.ts file handles all HTTP methods via named exports (GET, POST, etc.). Two route.ts files at the same path will always conflict regardless of which methods they export.

  3. Use middleware to rewrite one of the conflicting routes 85% fail

    Middleware rewrites happen at request time, but the route conflict is detected at build time during route resolution. The build will still fail before middleware can run.

Error Chain

Leads to:
Preceded by:
Frequently confused with: