---
title: Testing & troubleshooting microfrontends
product: vercel
url: /docs/microfrontends/troubleshooting
canonical_url: "https://vercel.com/docs/microfrontends/troubleshooting"
last_updated: 2018-10-20
type: reference
prerequisites:
  - /docs/microfrontends
related:
  - /docs/microfrontends/local-development
  - /docs/microfrontends/managing-microfrontends/vercel-toolbar
  - /docs/observability
  - /docs/tracing/session-tracing
  - /docs/tracing
summary: Learn about testing, common issues, and how to troubleshoot microfrontends on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# Testing & troubleshooting microfrontends

## Testing

The `@vercel/microfrontends` package includes test utilities to help avoid common misconfigurations.


<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [Microfrontends support is now in Public Beta](https://vercel.com/changelog/microfrontends-support-is-now-in-public-beta)
- [Managing microfrontends](https://vercel.com/docs/microfrontends/managing-microfrontends) — Learn how to manage your microfrontends on Vercel.
- [Managing microfrontends security](https://vercel.com/docs/microfrontends/managing-microfrontends/security) — Learn how to manage your Deployment Protection and Firewall for your microfrontend on Vercel.
- [Microfrontends](https://vercel.com/docs/agent-resources/vercel-mcp/tools/microfrontends) — Vercel MCP tools for microfrontends.
- [Get microfrontends config for a project](https://vercel.com/docs/rest-api/microfrontends/get-microfrontends-config-for-a-project) — GET /v1/microfrontends/projects/{projectIdOrName}/production-mfe-config — Get the microfrontends config for a project by
- [vercel microfrontends](https://vercel.com/docs/cli/microfrontends) — Manage microfrontends groups from the CLI. Learn how to create groups, inspect group metadata, add and remove projects,

Full cross-link map for this page: [/docs/microfrontends/troubleshooting.graph.md](/docs/microfrontends/troubleshooting.graph.md)
<!-- /docsgraph:related -->

### `validateMiddlewareConfig`

The `validateMiddlewareConfig` test ensures Middleware is configured to work correctly with microfrontends. Passing this test does *not* guarantee Middleware is set up correctly, but it should find many common problems.

Since Middleware only runs in the default application, you should only run this test on the default application. If it finds a configuration issue, it will throw an exception so that you can use it with any test framework.

The test fails when:

- The Middleware matcher doesn't match `/.well-known/vercel/microfrontends/client-config`.
- The Middleware matcher doesn't match a flagged path of a child application.
- The Middleware matcher matches a path that is always routed to a child application, including the child's `/<asset-prefix>/_next/:path+` assets. These requests never reach the default application's Middleware.

If your Middleware intentionally matches a child application path, pass that path in the optional third argument, `extraProductionMatches`, for example `validateMiddlewareConfig(config, './microfrontends.json', ['/docs/:path*'])`. Paths in this list that never match also fail the test.

```ts filename="tests/middleware.test.ts"
/* @jest-environment node */

import { validateMiddlewareConfig } from '@vercel/microfrontends/next/testing';
import { config } from '../middleware';

describe('middleware', () => {
  test('matches microfrontends paths', () => {
    expect(() =>
      validateMiddlewareConfig(config, './microfrontends.json'),
    ).not.toThrow();
  });
});
```

### `validateMiddlewareOnFlaggedPaths`

The `validateMiddlewareOnFlaggedPaths` test checks that Middleware is correctly configured for flagged paths by ensuring that Middleware rewrites to the correct path for these flagged paths. Since Middleware only runs in the default application, you should only run this testing utility in the default application.

```ts filename="tests/middleware.test.ts"
/* @jest-environment node */

import { validateMiddlewareOnFlaggedPaths } from '@vercel/microfrontends/next/testing';
import { middleware } from '../middleware';

// For this test to work, all flags must be enabled before calling
// validateMiddlewareOnFlaggedPaths. There are many ways to do this depending
// on your flag framework, test framework, etc. but this is one way to do it
// with https://flags-sdk.dev/
jest.mock('flags/next', () => ({
  flag: jest.fn().mockReturnValue(jest.fn().mockResolvedValue(true)),
}));

describe('middleware', () => {
  test('rewrites for flagged paths', async () => {
    await expect(
      validateMiddlewareOnFlaggedPaths('./microfrontends.json', middleware),
    ).resolves.not.toThrow();
  });
});
```

### `validateRouting`

The `validateRouting` test validates that the given paths route to the correct microfrontend. You should only add this test to the default application where the `microfrontends.json` file is defined.

```ts filename="tests/microfrontends.test.ts"
import { validateRouting } from '@vercel/microfrontends/next/testing';

describe('microfrontends', () => {
  test('routing', () => {
    expect(() => {
      validateRouting('./microfrontends.json', {
        marketing: ['/', '/products'],
        docs: ['/docs', '/docs/api'],
        dashboard: [
          '/dashboard',
          { path: '/new-dashboard', flag: 'enable-feature-x' },
        ],
      });
    }).not.toThrow();
  });
});
```

The above test confirms that microfrontends routing:

- Routes `/` and `/products` to the `marketing` microfrontend.
- Routes `/docs` and `/docs/api` to the `docs` microfrontend.
- Routes `/dashboard` and `/new-dashboard` (with the `enable-feature-x` flag enabled) to the `dashboard` microfrontend.

## Debugging routing

### Debug logs when running locally

See [debug routing](/docs/microfrontends/local-development#debug-routing) for how to enable debug logs to see where and why the local proxy routed the request.

### Debug headers when deployed

Debug headers expose the internal reason for the microfrontend response. You can use these headers to debug issues with routing.

You can enable debug headers in the [Vercel Toolbar](/docs/microfrontends/managing-microfrontends/vercel-toolbar#enable-routing-debug-mode), or by setting a cookie `VERCEL_MFE_DEBUG` to `1` in your browser.

Debug headers are only returned to users who are signed in to Vercel and have access to the project. If you aren't signed in, Vercel redirects you to sign in first.

Requests to your domain will then return additional headers on every response:

- `x-vercel-mfe-app`: The name of the microfrontend project that handled the request.
- `x-vercel-mfe-target-deployment-id`: The ID of the deployment that handled the request.
- `x-vercel-mfe-default-app-deployment-id`: The ID of the default application deployment, the source of the `microfrontends.json` configuration.
- `x-vercel-mfe-default-app-project-id`: The ID of the default application project.
- `x-vercel-mfe-zone-from-middleware`: For flagged paths, the name of the microfrontend that middleware decided should handle the request.
- `x-vercel-mfe-matched-path`: The path from `microfrontends.json` that was matched by the routing configuration.
- `x-vercel-mfe-response-reason`: The internal reason for the MFE response.

## Observability

Microfrontends routing information is stored in [Observability](/docs/observability) and can be viewed in the team or project scopes. Click on the Observability tab, and then find Microfrontends in the CDN section.

## Tracing

Microfrontends routing is captured by Vercel [Session tracing](/docs/tracing/session-tracing). Once you have captured a trace, you can inspect the Microfrontends span in the [logs section in the sidebar](/docs/tracing#viewing-traces-in-the-dashboard).

You may need to zoom in to the Microfrontends span. The span includes:

- `vercel.mfe.app`: The name of the microfrontend project that handled the request.
- `vercel.mfe.target_deployment_id`: The ID of the deployment that handled the request.
- `vercel.mfe.default_app_deployment_id`: The ID of the default application deployment, the source of the `microfrontends.json` configuration.
- `vercel.mfe.default_app_project_id`: The ID of the default application project.
- `vercel.mfe.app_from_middleware`: For flagged paths, the name of the microfrontend that middleware decided should handle the request.
- `vercel.mfe.matched_path`: The path from `microfrontends.json` that was matched by the routing configuration.

## Troubleshooting

The following are common issues you might face with debugging tips:

### Build fails with "Could not find a `microfrontends.json` file"

A build that ends with `Could not find a microfrontends.json file in the repository that contains the "<application>" application` means the application couldn't locate a `microfrontends.json` that lists it when it builds. Every application in the group reads `microfrontends.json` at build time through `withMicrofrontends`.

In a monorepo, each application searches the repository for the configuration automatically and matches applications by name. The build fails when:

- The application isn't listed under `applications` in `microfrontends.json`.
- The application's name in `microfrontends.json` doesn't match its Vercel project name. On Vercel, the application is identified by its project name. Outside of Vercel, such as in local builds, it's identified by the `projectName` in `.vercel/project.json` or, if that's missing, the `package.json` name. If the `package.json` name differs, add a `packageName` field to the application in `microfrontends.json`. See [Configuration](/docs/microfrontends/configuration).

In a [polyrepo](/docs/microfrontends/local-development#polyrepo-setup), the configuration lives in only one repository. When a child application builds on Vercel, Vercel provides the configuration from the default application's current production deployment. If the default application has no production deployment that includes `microfrontends.json`, deploy it to production first. For local development, and for builds that you run outside of Vercel, the other applications can't find the configuration unless you give them access:

- Pull the configuration into the application with `vercel microfrontends pull`, which writes it to the application's `.vercel` directory. See [Accessing the configuration file](/docs/microfrontends/local-development#accessing-the-configuration-file).
- Or set the `VC_MICROFRONTENDS_CONFIG` environment variable to the path of the configuration file.
- If the configuration uses a custom file name, set `VC_MICROFRONTENDS_CONFIG_FILE_NAME`. See [File naming](/docs/microfrontends/configuration#file-naming).

If you use a custom file name, add `VC_MICROFRONTENDS_CONFIG_FILE_NAME` as an [environment variable](/docs/environment-variables/managing-environment-variables) to every project in the microfrontends group so it applies during each build. Don't add `VC_MICROFRONTENDS_CONFIG` to a child application's project on Vercel: when it's set, the build reads only that path and not the configuration that Vercel provides.

### Microfrontends aren't working in local development

See [debug routing](/docs/microfrontends/local-development#debug-routing) for how to enable debug logs to see where and why the local proxy routed the request.

### Requests are not routed to the correct microfrontend in production

To validate where requests are being routed to in production, follow these steps:

1. [Verify](/docs/microfrontends/routing#identify-the-microfrontend-for-a-path) that the path is covered by the microfrontends routing configuration.
2. Inspect the [debug headers](/docs/microfrontends/troubleshooting#debug-headers-when-deployed) or view a [page trace](/docs/microfrontends/troubleshooting#tracing) to verify the expected path was matched.

### Pages Router pages fail during client-side navigation

Pages Router pages that use `getStaticProps` or `getServerSideProps` rely on
`/_next/data/...json` requests during client-side navigation. If Pages Router
support or the required proxy and routing behavior is missing, the page can work
on direct load but fail when you navigate to it from another microfrontend. This
can happen when navigating from an App Router page to a Pages Router page.

Check for these symptoms:

- `/_next/data` requests return a `404` response.
- `/_next/data` requests route to the wrong microfrontend.
- The page loads stale or incorrect data after navigation.

For any Next.js microfrontend that uses the Pages Router, enable
`supportPagesRouter` in `withMicrofrontends()`.

See [Set up microfrontends with your framework](/docs/microfrontends/quickstart#set-up-microfrontends-with-your-framework).

## QA checklist for Pages Router microfrontends

Use this checklist before promoting a microfrontends change that includes any
Next.js Pages Router routes:

- Test a direct page load.
- Test client-side navigation from another microfrontend into the Pages Router page.
- Test navigation from App Router pages to Pages Router pages.
- Test Pages Router pages that use `getStaticProps`.
- Test Pages Router pages that use `getServerSideProps`.
- Inspect network requests for `/_next/data`.
- Test through the [local microfrontends proxy](/docs/microfrontends/local-development#accessing-the-microfrontends-proxy).
- Test on a Preview deployment.

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
