The ENCORE_RUNTIME_LIB environment variable is not set (yarn start on Windows)

TL;DR

The runtime binary couldnt be located because I was starting the app with plain node instead of the Encore tooling. Another user hit the same error running npm run test with vitest.

Steps

1. What was going on

On Windows I cloned a minimal Encore repro and ran yarn start, which died with The ENCORERUNTIMELIB environment variable is not set. The runtime binary couldnt be located because I was starting the app with plain node instead of the Encore tooling. Another user hit the same error running npm run test with vitest. A maintainer answered on the thread, and the issue was closed in April 2025.

2. What fixed it

ENCORERUNTIMELIB points Encore at its native runtime binary, and when you launch with plain node or npm run test the variable is never set. The supported paths are to run the app with the Encore CLI (encore run) and run tests with encore test instead of npm run test, both set the environment up for you. If you really need to launch node directly, set ENCORERUNTIMELIB to the path of the encore-runtime binary yourself.

When to use

You are seeing this: What was going on On Windows I cloned a minimal Encore repro and ran yarn start, which died with The ENCORERUNTIMELIB environment variable is not set. Use this skill when you run into "The ENCORERUNTIMELIB environment variable is not set (yarn start on Windows)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

In the thread, the question was: On Windows I cloned a minimal Encore repro and ran yarn start, which died with The ENCORERUNTIMELIB environment variable is not set. The runtime binary couldnt be located because I was starting the app with plain node instead of the Encore tooling. Another user hit the same error running npm run test with vitest. A maintainer answered on the thread, and the issue was closed in April 2025. The verified resolution: ENCORERUNTIMELIB points Encore at its native runtime binary, and when you launch with plain node or npm run test the variable is never set. The supported paths are to run the app with the Encore CLI (encore run) and run tests with encore test instead of npm run test, both set the environment up for you. If you really need to launch node directly, set ENCORERUNTIMELIB to the path of the encore-runtime binary yourself. Thread: https://vectle.com/threads/thr_54k6KA0WdLCCUIfTZtA5PQ