The ENCORE_RUNTIME_LIB environment variable is not set

[rtritto]

Reproduction

repository=repro-encore-win ~ branch=missing-env

• git clone https://github.com/rtritto/repro-encore-win.git
• cd repro-encore-win
• git checkout missing-env
• yarn
• yarn start OR node ./start.mjs

  C:\Users\<USER>\AppData\Local\Yarn\Berry\cache\encore.dev-npm-1.44.6-3d86b75c4d-10c0.zip\node_modules\encore.dev\dist\internal\runtime\napi\napi.cjs:7
    throw new Error(
          ^
  
  Error: The ENCORE_RUNTIME_LIB environment variable is not set. It must be set to the path of the Encore runtime library ('encore-runtime.node').
      at Object.<anonymous> (C:\Users\<USER>\AppData\Local\Yarn\Berry\cache\encore.dev-npm-1.44.6-3d86b75c4d-10c0.zip\node_modules\encore.dev\dist\internal\runtime\napi\napi.cjs:7:9)  
      at Module._compile (node:internal/modules/cjs/loader:1546:14)
      at Module._extensions..js (node:internal/modules/cjs/loader:1691:10)
      at require$$0.Module._extensions..js (C:\repro-encore-win\.pnp.cjs:9800:33)
      at Module.load (node:internal/modules/cjs/loader:1317:32)
      at Module._load (node:internal/modules/cjs/loader:1127:12)
      at require$$0.Module._load (C:\repro-encore-win\.pnp.cjs:9648:31)
      at TracingChannel.traceSync (node:diagnostics_channel:315:14)
      at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)
      at cjsLoader (node:internal/modules/esm/translators:329:5

Info

OS: Windows 11
Node: v22
encore.dev: v1.44.6 (same behavior with v1.44.5)
encode installed v1.44.5
yarn berry with PnP (Plug'n'Play)

[rtritto]

I fixed with env var: ENCORE_RUNTIME_LIB=C:\Users\<USER>\.encore\runtimes\js\encore-runtime.node
I didn't find any ENCORE_RUNTIME_LIB occurence in documentation.

---

The load of encore-runtime.node binary can be improved:

• remove references of env var ENCORE_RUNTIME_LIB
• the install of Encore (install-the-encore-cli) should create the env var ENCORE_PATH=C:\Users\<USER>\.encore
• the JS encore.dev should get the correct path of encore-runtime.node: ENCORE_PATH + \runtimes\js\encore-runtime.node
• the GO encore.dev should get the correct path of Encore runtime for GO: ENCORE_PATH + \runtimes\go\...

If an user want to change the path, he must change both PATH (default C:\Users\<USER>\.encore\bin) and ENCORE_PATH (default C:\Users\<USER>\.encore) env vars.

Note: documentation also needs to be updated

[fredr]

Hey @rtritto

To start encore locally, you should use the encore cli that will setup all infra and env, e.g:

encore run

[rtritto]

Hi @fredr, this issue is related to the JS environment (the start of the server is a separated environment)

[tdanh2k]

And the Linux version of the fix for those who's struggling

export ENCORE_INSTALL="/home/danhpc/.encore"
export PATH="$ENCORE_INSTALL/bin:$PATH"
export ENCORE_RUNTIME_LIB="$ENCORE_INSTALL/runtimes/js/encore-runtime.node"

[fredr]

@rtritto could you explain a bit what you are trying to solve? In what scenario do you want to run it this way?

[rtritto]

@fredr the JS encore.dev dependency should use a default value to load JS runtime encore-runtime.node file.
encore-runtime.node file is located in C:/Users/<USER>/.encore/runtimes/js (Windows) or in /home/<USER>/.encore/runtimes/js (Linux).

To achieve that, we have at least 3 alternatives:

• Solution 1 (IMO simple and less invasive):
  • on encore OS install
    • introduce a new env var ENCORE_PATH where the value will be C:/Users/<USER>/.encore (Windows) or /home/<USER>/.encore (Linux)
    • set PATH env var with value $ENCORE_PATH/bin;$PATH (Windows) or $ENCORE_PATH/bin:$PATH (Linux)
  • the JS encore.dev dependency loads process.env.ENCORE_PATH + /runtimes/js/encore-runtime.node
  • Note: ENCORE_RUNTIME_LIB env var isn't needed and can be removed
• Solution 2:
  • on encore OS install
    • set ENCORE_RUNTIME_LIB env var with value C:/Users/<USER>/.encore/runtimes/js/encore-runtime.node (Windows) or /home/<USER>/.encore/runtimes/js/encore-runtime.node (Linux)
  • the JS encore.dev dependency loads process.env.ENCORE_RUNTIME_LIB
• Solution 3 (The ENCORE_RUNTIME_LIB environment variable is not set #1611 (comment)):
  • on encore OS install
    • introduce a new env var ENCORE_PATH where the value will be C:/Users/<USER>/.encore (Windows) or /home/<USER>/.encore (Linux)
    • set PATH env var with value $ENCORE_PATH/bin;$PATH (Windows) or $ENCORE_PATH/bin:$PATH (Linux)
    • set ENCORE_RUNTIME_LIB env var with value $ENCORE_PATH/runtimes/js/encore-runtime.node (Windows) or $ENCORE_PATH/runtimes/js/encore-runtime.node (Linux)
  • the JS encore.dev dependency loads process.env.ENCORE_RUNTIME_LIB

Also the documentation needs to be updated with all references and env vars.

---

My scenario is the development.

[eandre]

I still don't understand what you're trying to do; under what circumstance is the ENCORE_RUNTIME_LIB variable not set today? The encore daemon automatically sets it whenever you're running encore run, and it's being embedded into any Docker images built via encore build docker. So what are you trying to do, exactly?

[rtritto]

I still don't understand what you're trying to do; under what circumstance is the ENCORE_RUNTIME_LIB variable not set today? The encore daemon automatically sets it whenever you're running encore run, and it's being embedded into any Docker images built via encore build docker. So what are you trying to do, exactly?

I have a project with a file that imports encore.dev/api.

The setup of encore should set the ENCORE_RUNTIME_LIB env var becuase it also set bin path in the PATH env var.

The APIs should be started using an entrypoint from a file in the project.

Also I don't need the dashboard service that encore run starts.

Maybe Encore was designed to work differently.

[eandre]

It is not designed to be used like that, no. Due to how Encore's request decoding/response encoding works, it requires the pre-computed API schemas to be provided ("the metadata"). This must be provided via ENCORE_APP_META or via ENCORE_APP_META_PATH.

What's more, all of Encore's infrastructure resources additionally require runtime configuration to be provided, so that Encore's runtime knows where the infrastructure is located, what implementation to use, how to authenticate, etc.

In short, setting ENCORE_RUNTIME_LIB is far from sufficient. That's why Encore provides encore run, which takes care of setting up the infrastructure the application requires, computes the metadata and propagates it to the application, etc. (You can disable the dashboard with encore run --browser=never)

[rtritto]

Ok, thanks for the infos.

So if ENCORE_RUNTIME_LIB env var was chosen to be set with encore run, imo, this issue can be closed.

In the JS encore.dev dependency, maybe it's better to add an error message. Eg: Missing "ENCORE_RUNTIME_LIB" env var. Start "encore run" first.

[eandre]

I feel like the error message is reasonably clear as-is? It seems incorrect to mention Start "encore run" first because that isn't used when running in the cloud or running a built docker image. If something is misconfigured for such an environment you would also that same error, and then the suggestion to encore run is going to cause a lot of confusion. On balance I think we should leave it as-is for now.