Nuxt•7d ago

GetPortError: Timeout waiting for port 49281 after 20 retries with 500ms interval.

I'm trying to write an e2e test which is very basic:

import { setup, createPage, url } from '@nuxt/test-utils/e2e';
import { describe, it, expect } from 'vitest';

describe('todo', async () => {
  await setup({
    nuxtConfig: {
      sourcemap: false,
      nitro: {
        preset: 'node-listener',
      },
    },
  });

  it('todo', async () => {
    expect(1).toBe(1);
  });
});

import { setup, createPage, url } from '@nuxt/test-utils/e2e';
import { describe, it, expect } from 'vitest';

describe('todo', async () => {
  await setup({
    nuxtConfig: {
      sourcemap: false,
      nitro: {
        preset: 'node-listener',
      },
    },
  });

  it('todo', async () => {
    expect(1).toBe(1);
  });
});

But when I run the test I get the following error: GetPortError: Timeout waiting for port 49281 after 20 retries with 500ms interval. How can I go about debugging this? When I start the app locally for local dev (pnpm dev) the app starts up just fine. No problem opening the app on localhost port 3000 when doing local dev. But for some reason it times out waiting for a port when doing an e2e test.

5 Replies

kapa.ai•7d ago

Hi @AGill. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- This error comes from the test server failing to start on the randomly chosen port before the timeout. From the linked Nuxt/Test Utils and docs PRs, there are a few relevant points: 1. Use the recommended Vitest projects config + Nuxt test-utils presets The older “simple” Vitest setup is deprecated and can cause unintended behaviour with environments and server startup; Nuxt recommends using Vitest projects with @nuxt/test-utils configuration instead of ad‑hoc setup. [testing docs update] Concretely, you should: - Configure Vitest via defineVitestConfig/projects - Use the Nuxt e2e preset from @nuxt/test-utils/e2e - Avoid custom environments unless needed If your current setup predates these docs, updating to the new pattern often fixes flaky “server didn’t start” / port errors. 2. Increase Nuxt test-utils timeouts Nuxt test-utils exposes setupTimeout and teardownTimeout options (recently documented) – these are specifically about how long it waits for Nuxt to boot/tear down. [testing timeouts] In your setup call, try:

   await setup({
     setupTimeout: 120_000,     // 120s, for debugging
     teardownTimeout: 120_000,  // optional, but good to add
     nuxtConfig: {
       sourcemap: false,
       nitro: {
         preset: 'node-listener',
       },
     },
   });

   await setup({
     setupTimeout: 120_000,     // 120s, for debugging
     teardownTimeout: 120_000,  // optional, but good to add
     nuxtConfig: {
       sourcemap: false,
       nitro: {
         preset: 'node-listener',
       },
     },
   });

If the timeout is the only problem, this should at least change the behaviour or reveal more logs. 3. Let Nuxt pick its own listener in tests You are forcing nitro.preset = 'node-listener'. Under e2e, Nuxt test-utils already manages how Nuxt is started (including port selection and listening behaviour). The knowledge sources don’t explicitly say this preset is incompatible with e2e, but they also don’t show it used in examples. To isolate the issue, remove the preset for now:

   await setup({
     nuxtConfig: {
       sourcemap: false,
       // remove nitro.preset for debugging
     },
   });

   await setup({
     nuxtConfig: {
       sourcemap: false,
       // remove nitro.preset for debugging
     },
   });

If this resolves the error, the combination of node-listener and the e2e runner is likely what’s breaking port detection. 4. Check that the dev server URL and port are configured dynamically Nuxt has recently fixed issues where dev server URLs and ports were hardcoded (e.g. <http://localhost:3000>) instead of being derived from the actual host/port. [dynamic devServer url]
If you’re on an older Nuxt version, upgrading to a version that includes this fix can resolve cases where the test runner thinks it’s starting a server on a random port, but the app actually binds elsewhere. --- If after: - using the recommended Vitest projects setup, - removing nitro.preset: 'node-listener' temporarily, - increasing setupTimeout, you still see GetPortError, then the knowledge sources don’t provide a more specific debugging path (like enabling extra logs for the port waiter itself). In that case I’d suggest: - ensuring you’re on the latest Nuxt + @nuxt/test-utils versions, and - opening an issue with a minimal reproduction repo, since this may be an environment‑specific bug not covered in the current docs/PRs. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•7d ago

<@508382519146709018> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

AGillOP•6d ago

Hey @kapa.ai none of the suggestions worked. But what does work is setting the dev option to true

  await setup({
    dev: true,
  });

  await setup({
    dev: true,
  });

Do you know what the dev option does? It's not documented. I am guessing it sets NODE_ENV=development but I'm not sure. Also, can you explain why setting this option lets me connect to the port when no other configuration could?

kapa.ai•6d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- dev is a Nuxt option that controls whether Nuxt runs in development or production mode. In your case:

await setup({
  dev: true,
});

await setup({
  dev: true,
});

means: “start Nuxt in dev mode inside the test runner”. From the Nuxt side, there are two relevant pieces of information in the sources: 1. Nuxt has an explicit dev/test environment concept that is not just NODE_ENV. There was a bug where these values got hard‑coded when @nuxt/schema was imported before overriding NODE_ENV, and a fix was added so that dev / test can be overridden reliably. [schema env fix]
This tells us: - There is a dev flag in the Nuxt schema. - It can be set independently of NODE_ENV (and was buggy when you tried to override it only via NODE_ENV). 2. Nuxt has separate behaviour “in dev” vs “in prod” in various places (e.g. the ability to disable scripts but keep Vite’s dev connection only in dev, or special handling of import.meta.dev in tests). [disable scripts in dev; stub import.meta.dev]
That implies that a lot of “server startup” and tooling code paths are gated on whether dev is true. However, the knowledge sources do not contain: - A direct definition of the dev option in @nuxt/test-utils. - A statement that dev: true sets NODE_ENV=development. So I cannot confirm from these documents whether dev also mutates NODE_ENV, only that it controls Nuxt’s own environment flags. --- Why does dev: true make your e2e test work? Based on what is documented: - Nuxt’s environment handling had issues when dev/test defaults were computed before you changed NODE_ENV, which affected how configs were applied. [schema env fix] - A lot of logic branches on “dev vs prod”, including how the dev server and Vite are wired up. [disable scripts in dev; stub import.meta.dev] Putting that together, the most we can safely say from the sources is: - When you pass dev: true to setup, you are forcing Nuxt into its development mode for that test run. - In dev mode, Nuxt uses its dev server/Vite paths, which apparently start and listen correctly in your environment. - In the default (non‑dev) mode, Nuxt is behaving as “production” inside the test runner, and whatever path it uses there (building + starting Nitro, port negotiation, etc.) is failing to come up before the port‑waiter times out. The exact failing step is not described in the sources. So: - dev: true switches your tests to “Nuxt dev mode”, which uses a different startup path that successfully binds a port. - The knowledge provided doesn’t explain exactly which part of the prod/e2e startup is broken in your case, only that environment handling and dev/prod branching are sensitive and have had recent fixes. If you need a deeper, line‑by‑line explanation of what dev does inside @nuxt/test-utils or how it affects the port waiter, that’s not covered in the current docs/PRs; you’d need to inspect @nuxt/test-utils’ source or open an issue with your reproduction. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•6d ago

<@508382519146709018> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

GetPortError: Timeout waiting for port 49281 after 20 retries with 500ms interval.

Did you find this page helpful?