Env vars validation failed
I just started get the "Env vars validation failed" error (Error: Error parsing environment variables) when I run wasp start. I don't recall ever working on any env variable. How do I fix this??
20 Replies
Hi @Kynetix. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
The "Env vars validation failed" or "Error parsing environment variables" error when running wasp start usually means that one or more required environment variables are missing or incorrectly set in your project.
Here’s how you can troubleshoot and fix this:
1. Check for Required Env Vars
Wasp requires certain environment variables to be set, especially for the server. Common required variables include: -
- For development, use
- For production, set them in your deployment environment (e.g., using
- Make sure there are no typos in variable names. - Ensure all required variables are present and have values. - If you recently updated Wasp or your project, new required variables may have been introduced. 4. Restart Wasp
After fixing your env files, restart your development server: If you’re still seeing the error after checking the above, look for more specific error messages in your terminal—they often mention which variable is missing or invalid. If you’re using a template or example project, check its documentation or README for any project-specific env vars you might need to set. If you have not edited any env files but still get this error after an upgrade, it’s possible that the new Wasp version introduced new required env vars. Double-check the docs or the error message for hints on what’s missing. For more on how Wasp handles env vars and validation, see the project env vars documentation and deployment environment variables. If you need to see an example of how env var validation might look in code, see this discussion for a sample using Zod for validation. If you’re still stuck, please share the full error message (it often specifies which variable is missing or invalid), and I can help you further! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ---------------------- Sorry @Kynetix, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist: Perhaps try again in 15mins?
Wasp requires certain environment variables to be set, especially for the server. Common required variables include: -
DATABASE_URL
- WASP_WEB_CLIENT_URL
- WASP_SERVER_URL
- JWT_SECRET (if using Wasp Auth)
- PORT (optional, defaults to 3001)
If you’re using social auth (like Google or GitHub), you’ll also need to set their respective client IDs and secrets. You can find a full list and explanations in the deployment docs.
2. Where to Set Env Vars- For development, use
.env.server (for server vars) and .env.client (for client vars) in your project root.- For production, set them in your deployment environment (e.g., using
flyctl secrets set for Fly.io).
Example .env.server:
Example .env.client:
More details: Defining Env Vars in Development
3. Validate Your Env Files- Make sure there are no typos in variable names. - Ensure all required variables are present and have values. - If you recently updated Wasp or your project, new required variables may have been introduced. 4. Restart Wasp
After fixing your env files, restart your development server: If you’re still seeing the error after checking the above, look for more specific error messages in your terminal—they often mention which variable is missing or invalid. If you’re using a template or example project, check its documentation or README for any project-specific env vars you might need to set. If you have not edited any env files but still get this error after an upgrade, it’s possible that the new Wasp version introduced new required env vars. Double-check the docs or the error message for hints on what’s missing. For more on how Wasp handles env vars and validation, see the project env vars documentation and deployment environment variables. If you need to see an example of how env var validation might look in code, see this discussion for a sample using Zod for validation. If you’re still stuck, please share the full error message (it often specifies which variable is missing or invalid), and I can help you further! ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ---------------------- Sorry @Kynetix, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist: Perhaps try again in 15mins?
@kapa.ai I've verified that the required variables are there, both in .env.server and .env.client, but the error persists. The error log doesn't help either - it just says
[ Server ] 🚀 "Google" auth initialized
[ Server ] 🚀 "Email and password" auth initialized
[ Server!]
[ Server!] ══ Env vars validation failed ══ [ Server!] [ Server!] - Required [ Server!] [ Server!] ════════════════════════════════ [ Server!] /Users/xxxx/projects/zzzz/app/.wasp/out/sdk/wasp/dist/env/validation.js:16 [ Server!] throw new Error('Error parsing environment variables'); [ Server!] ^ [ Server!] [ Server!] [ Server!] Error: Error parsing environment variables [ Server!] at ensureEnvSchema (/Users/xxx/projects/zzz/app/.wasp/out/sdk/wasp/dist/env/validation.js:16:19) [ Server!] at <anonymous> (/Users/xxx/projects/zzz/app/.wasp/out/sdk/wasp/dist/client/env.js:13:20) [ Server!] at ModuleJob.run (node:internal/modules/esm/module_job:271:25) [ Server!] at async onImport.tracePromise.proto (node:internal/modules/esm/loader:578:26) [ Server!] at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5) [ Server!] [ Server!] Node.js v22.14.0
[ Server!] ══ Env vars validation failed ══ [ Server!] [ Server!] - Required [ Server!] [ Server!] ════════════════════════════════ [ Server!] /Users/xxxx/projects/zzzz/app/.wasp/out/sdk/wasp/dist/env/validation.js:16 [ Server!] throw new Error('Error parsing environment variables'); [ Server!] ^ [ Server!] [ Server!] [ Server!] Error: Error parsing environment variables [ Server!] at ensureEnvSchema (/Users/xxx/projects/zzz/app/.wasp/out/sdk/wasp/dist/env/validation.js:16:19) [ Server!] at <anonymous> (/Users/xxx/projects/zzz/app/.wasp/out/sdk/wasp/dist/client/env.js:13:20) [ Server!] at ModuleJob.run (node:internal/modules/esm/module_job:271:25) [ Server!] at async onImport.tracePromise.proto (node:internal/modules/esm/loader:578:26) [ Server!] at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5) [ Server!] [ Server!] Node.js v22.14.0
Let me check the knowledge base for you again. One moment! :books:
----------------------
Based on your error log and the information from the knowledge sources, here are some focused troubleshooting steps:
1. Check for Trailing Slashes and URL Format
There have been issues in Wasp where environment variables like
Make sure there are no typos in the variable names in your
Since you are using Google and Email/Password auth, ensure you have set the following in
The error log shows you are using Node.js v22.14.0. The knowledge sources mention issues with certain Node.js versions, and Wasp is known to work with Node.js 18.x and 20.x. Try downgrading your Node.js version to 18 or 20 and see if the error persists Discord thread. 5. Clean and Rebuild
After making changes, run: This ensures that any cached or stale files are removed and the environment is rebuilt with the latest variables. 6. Check for Hidden Characters
Sometimes, invisible characters (like spaces or BOM) in your
There have been issues in Wasp where environment variables like
WASP_WEB_CLIENT_URL or REACT_APP_API_URL cause validation errors if they have (or are missing) a trailing slash, or if the URL format is not valid. Even if the variable is present, its value must be a valid URL and match the expected format (e.g., no trailing slash if not expected) Ensure the REACT_APP_API_URL and WASP_WEB_CLIENT_URL env vars are valid URLs.
2. Double-Check Variable Names and ValuesMake sure there are no typos in the variable names in your
.env.server and .env.client files. The names must match exactly what Wasp expects (e.g., WASP_WEB_CLIENT_URL, not WASP_WEBCLIENT_URL).
3. Required Variables for AuthSince you are using Google and Email/Password auth, ensure you have set the following in
.env.server:
as described in the Google Auth docs.
4. Node.js VersionThe error log shows you are using Node.js v22.14.0. The knowledge sources mention issues with certain Node.js versions, and Wasp is known to work with Node.js 18.x and 20.x. Try downgrading your Node.js version to 18 or 20 and see if the error persists Discord thread. 5. Clean and Rebuild
After making changes, run: This ensures that any cached or stale files are removed and the environment is rebuilt with the latest variables. 6. Check for Hidden Characters
Sometimes, invisible characters (like spaces or BOM) in your
.env files can cause parsing errors. Try recreating the files or copy-pasting the contents into a new file.
If you have verified all the above and the error still persists, and the error log does not specify which variable is problematic, it may be a bug or a very subtle formatting issue. In that case, try commenting out variables one by one to isolate the problematic one, or share your .env.server (with secrets redacted) for more targeted help.
The knowledge sources do not provide more detailed error diagnostics for this specific validation error, so if none of the above resolves it, consider opening an issue on the Wasp GitHub or asking in the Discord for further assistance.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------
Sorry @Kynetix, I seem to be having a bit of trouble. Don't worry though, I've pinged my support and they will try to fix me up! :technologist:
Perhaps try again in 15mins?Have you added any env validation rules yourself?
Env Variables | Wasp
Environment variables are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production.
No, didn't know about it @miho. I'll give it a shot. Thanks.
It's kinda odd that the error log doesn't specify which env variable failed the validation
I tried it, but the error persists
How does your Wasp file look like?
Here are the main.wasp file, the env.ts and the env client & server files (redacted). Hope this helps. I've been at this for days, and I'm trying to launch the product for beta testing this month!
I really appreciate your help, @miho
And this is the terminal.
I see it is trigger client env validation on the server which I find really odd. I don't have any immediate ideas how this happened.
Please send me a zip of your project in the DMs 🙂 I'll trying debugging it for you and report back.
Thanks man
👉 Importing
import { createTransactionAction } from 'wasp/client/operations'; in the apis.ts file on the server triggers the issue. You can't import wasp/client/* modules on the server.
Read more on how to use actions on the server here: https://wasp.sh/docs/data-model/operations/actions#using-actions
That explains it - it tries to validate client env vars in the server context but it doesn't have the client env var object (import.meta.env) which is supposed to be an object. In this case it is undefined and it fails the whole initial assumption that there will be an object that contains env variables.Created these two issues to improve how we handle this situation:
- https://github.com/wasp-lang/wasp/issues/3045
- https://github.com/wasp-lang/wasp/issues/3044
GitHub
Output a better error message if environemnt variables object is `u...
Related to #3044 where we noted: This happens because the client env variables trigger immediately via a side-effect. The object which the client env validation is looking for is import.meta.env wh...
GitHub
Validate that users are not importing anything from the `wasp/clien...
Based on this message: https://discord.com/channels/686873244791210014/1402311673993367632/1402570590832951368 If users import something from the wasp/client/* modules on the server, it will fail w...
Thanks, @miho I made the change and ran wasp clean && wasp start, but the error still occurs.
Check in your serve code if you are importing
wasp/client/* somewhere. Make sure to save any changes you made. Is the error identical?Yep, checked all server *.ts files for wasp/client/ . The error's identical.
Does it mean it has nothing to do with the variables in the .env files?
You also had
import { env } from 'wasp/client'; in your websockets.ts file. It worked for me after I removed that one as well 🙂
You need to split your websockets code into client and server for now.
Thanks, that fixed it (removing it from websockets.ts). Spent an entire week on this!
I wonder why, though.
Hey @Kynetix, wonder why what exactly?
If it's why the issue happens, then:
The problem with importing client stuff on the server is that client code assumes it has access to client environment variables. Since we are on the server environment they don't exist. So we fail the client env variable validation.