How to Fix: Module not found: Can’t resolve ‘***\app\favicon.ico?__next_metadata__’

5 min read Aldawsari
5 min read

This error is a Next.js App Router metadata resolution failure: the framework is trying to build metadata for app/favicon.ico, but the referenced file cannot be resolved during compilation, so development mode crashes with Module not found: Can't resolve '.../app/favicon.ico?__next_metadata__'.

Understanding the Root Cause

In modern Next.js, especially when using the App Router, files like favicon.ico, icon.png, apple-icon.png, and other metadata assets can be discovered automatically from the app directory. During compilation, Next.js generates internal metadata imports with query strings such as ?__next_metadata__.

If the build process finds a metadata reference but the actual file is missing, misnamed, invalid, or located in the wrong directory, webpack cannot resolve that generated import. That is why the error message points to:

app/favicon.ico?__next_metadata__

Technically, the issue usually happens for one of these reasons:

  • The project expects a favicon file inside the app directory, but it does not exist.
  • The file exists with the wrong name or extension, such as favicon.png while metadata expects favicon.ico.
  • The app mixes manual metadata declarations with automatic file-based metadata in a way that leaves a broken reference.
  • The file path behaves differently across environments because of case sensitivity. For example, Windows may tolerate naming mismatches that fail on Linux or in CI.
  • A stale .next cache is still referencing an old metadata asset that was removed or renamed.

For this issue, the most likely root cause is simple: Next.js is looking for app/favicon.ico, but that file is missing or not resolvable in the repository structure.

Step-by-Step Solution

The fix is to provide a valid favicon in the correct location and make sure metadata configuration does not point to a non-existent file.

1. Check whether app/favicon.ico exists

From the project root, verify the file is present:

ls app

On Windows PowerShell:

Get-ChildItem app

You should see:

app/favicon.ico

If it is missing, create or copy one into that folder.

2. Add a valid favicon file

If your project already has a favicon somewhere else, move or copy it into the app directory:

project-root/
  app/
    favicon.ico
    layout.tsx
    page.tsx

If you do not have one yet, create a minimal favicon and save it exactly as favicon.ico.

3. If your favicon lives in public, do not rely on file-based metadata from app

An alternative approach is to store the icon in public/favicon.ico and reference it explicitly in metadata. For example, in app/layout.tsx:

import type { Metadata } from 'next'

export const metadata: Metadata = {
  icons: {
    icon: '/favicon.ico',
  },
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

If you use this approach, make sure there is no broken app/favicon.ico reference left behind.

4. Remove conflicting metadata assets

Check for duplicate or confusing icon files:

app/icon.png
app/favicon.ico
app/apple-icon.png

These are valid in Next.js, but if you renamed or deleted one recently, clean up the metadata strategy so it is consistent. Either:

  • Use file-based metadata in the app directory, or
  • Use explicit metadata.icons paths from public.

Do not leave the framework trying to auto-resolve a file that no longer exists.

5. Clear the Next.js build cache

After restoring or moving the icon, clear cached output:

rm -rf .next

On Windows PowerShell:

Remove-Item -Recurse -Force .next

Then reinstall and restart the dev server:

npm install
npm run dev

6. Verify the final directory structure

A working setup should look like one of these:

Option A: File-based metadata inside app

app/
  favicon.ico
  layout.tsx
  page.tsx

Option B: Explicit metadata using public

public/
  favicon.ico

app/
  layout.tsx
  page.tsx

With layout.tsx containing:

export const metadata = {
  icons: {
    icon: '/favicon.ico',
  },
}

For the linked repository, the safest fix is:

  1. Add a real favicon.ico file to the app directory, or
  2. Move the favicon to public/favicon.ico and define it explicitly in app/layout.tsx.

If you want the least surprising setup for teams and deployments, the public + metadata.icons approach is usually the clearest.

import type { Metadata } from 'next'

export const metadata: Metadata = {
  icons: {
    icon: '/favicon.ico',
  },
}

Common Edge Cases

  • Wrong filename case: Favicon.ico is not the same as favicon.ico on case-sensitive systems.
  • Wrong extension: A file named favicon.png will not satisfy a generated import for favicon.ico.
  • Broken Git tracking: The file exists locally but was never committed, so other environments fail.
  • Corrupted icon file: Rare, but invalid binary content can trigger asset processing issues.
  • Conflicting router structure: Mixing old pages router conventions with app router metadata patterns can create confusion.
  • Cache persistence: Even after fixing the file, the error may continue until .next is deleted.
  • Monorepo path assumptions: If the app is nested, ensure the favicon is inside the correct app package, not only at the workspace root.

FAQ

Why is Next.js adding ?__next_metadata__ to the favicon path?

That query string is part of Next.js internal metadata bundling. It transforms metadata assets into internal module imports so webpack can process them during build time.

Can I keep the favicon in public instead of app?

Yes. Put the file in public/favicon.ico and reference it explicitly through metadata.icons in app/layout.tsx. That is a clean and reliable setup.

Why does the app compile first and then fail afterward?

Some metadata-related imports are resolved during later stages of the dev build pipeline. Initial compilation may appear successful, but once Next.js processes the route metadata graph, the missing icon import causes the crash.

In short, the fix is not in webpack configuration or dependency versions. It is in restoring a valid favicon metadata asset where Next.js App Router expects it, then clearing the build cache and restarting the dev server. If the repository is missing app/favicon.ico, that is the exact file to fix first.

Leave a Reply

Your email address will not be published. Required fields are marked *