SolidStart env var undefined without VITE_ prefix in CI

By Daniel Zoghalchali·Latchkey

SolidStart uses Vite, which only inlines environment variables prefixed with VITE_ into client bundles. A variable set in CI without that prefix is not exposed to import.meta.env, so it reads undefined at build time.

What this error means

A client value from import.meta.env.MY_KEY is undefined in the built app, or the build embeds an empty string, even though the CI secret is set.

TypeError: Cannot read properties of undefined (reading 'toString')
  const key = import.meta.env.API_KEY; // undefined: not VITE_ prefixed

Common causes

The variable lacks the VITE_ prefix

Vite deliberately excludes non-VITE_ variables from client bundles to avoid leaking server secrets, so an unprefixed name is never inlined.

The env was set only at deploy, not at build

Client env is inlined at build time; setting it only at runtime leaves the built value empty.

How to fix it

Prefix client variables with VITE_

1. Rename client-facing variables to start with VITE_.
2. Set them in the build step env, not only at deploy time.
3. Read them via import.meta.env.VITE_X.

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

Keep secrets server-side

Do not expose real secrets to the client; read them inside a server function instead of inlining with VITE_.

How to prevent it

• Prefix every client env var with VITE_.
• Set client env in the build step, since Vite inlines at build time.
• Never put true secrets behind a VITE_ prefix.

Frequently asked questions

Related guides

References

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