Qwik env var undefined without PUBLIC_ prefix in CI

By Daniel Zoghalchali·Latchkey

Qwik only exposes environment variables prefixed with PUBLIC_ to client code through import.meta.env. A variable set in CI without that prefix is kept server-side, so reading it on the client returns undefined.

What this error means

A client value from import.meta.env.PUBLIC_X is undefined in the built app, or reading an unprefixed name on the client yields nothing, even though the CI variable is set.

TypeError: Cannot read properties of undefined (reading 'trim')
  const url = import.meta.env.API_URL; // undefined on client: needs PUBLIC_ prefix

Common causes

The variable lacks the PUBLIC_ prefix

Qwik/Vite exclude non-PUBLIC_ variables from client bundles to avoid leaking secrets, so an unprefixed name is never exposed to the browser.

Reading a server env on the client

Server-only values are available via routeLoader$/server code, not import.meta.env on the client.

How to fix it

Prefix client variables with PUBLIC_

1. Rename client-facing variables to start with PUBLIC_.
2. Set them in the build step env.
3. Read them via import.meta.env.PUBLIC_X on the client.

env:
  PUBLIC_API_URL: ${{ vars.API_URL }}
# in code:
const url = import.meta.env.PUBLIC_API_URL;

Read secrets server-side

Access non-public values inside routeLoader$/server$ using the platform env, never on the client.

How to prevent it

• Prefix every client env var with PUBLIC_.
• Keep secrets out of PUBLIC_ variables.
• Read server-only env inside server code, not import.meta.env on the client.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation