v4.4.1: ConfigurationError thrown in pipeline as variables are not available on build time

[jesseflikweerteo]

Checklist

• The issue can be reproduced in the nextjs-auth0 sample app (or N/A).
• I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

After upgrading our SDK from v4.4.0 to v4.4.1 our webapp won't build in the pipeline anymore. Our AUTH0_... variables are defined in the Azure App Service (so they're only available in the backend), but not in the build step. We're not planning on adding those non-NEXT_PUBLIC_ variables to the pipeline either, as that might confuse developers since they're not the variables actually used in the webapp; non-NEXT_PUBLIC_ variables are defined in the App Service.

Would it be possible to create a way to disable the validation of variables by e.g. setting a single environment variable, like AUTH0_OVERRIDE_VARIABLE_VALIDATION? Not relevant to this specific issue, but how was this change only a patch instead of a minor version bump?

Reproduction

1. Try to build your Next 14 WebApp without all required non-NEXT_PUBLIC_ variables (like domain, clientId, appBaseUrl, secret and clientAuthentication)
2. Notice that building is not possible
3. Find out that disabling the validation is not possible

Additional context

No response

nextjs-auth0 version

v4.4.1

Next.js version

v14.2.26

Node.js version

v20.10.0

[robcaldecott]

Same issue here, this is breaking our NextJS docker builds.
I think we had this issue in the early v4 betas and it was fixed.
We will have to roll back to an earlier release.

[frederikprijck]

We're not planning on adding those non-NEXT_PUBLIC_ variables to the pipeline either, as that might confuse developers since they're not the variables actually used in the webapp;

I think it is not uncommon for a library to enforce validation of configuration options that are required to properly use the SDK, the goal is ofcourse the help signal what's missing as soon as possible to improve the onboard experience.

In your case, why do you expect Auth0Client to be initializable without the expected values in such a way that you do not want to configure them in the environments that need to initialiaze it ?

Not relevant to this specific issue, but how was this change only a patch instead of a minor version bump?

We considered a minor or a patch. But arguably it isn't a minor, and is more of a patch in the sense that we are fixing the lack of proper validation. We didnt change anything in terms of the functional SDK. Our Auth0Client was never usable anyway without providing the values in question anyway.

[robcaldecott]

We create a single docker build using npm run build and then deploy this to various environments with the AUTH0 variables being set per-environment in advance of npm start. We use a different set of Auth0 credentials for different target environments. It will be very difficult for us to use variables when we create the build.

I don't understand why this change is necessary, it was already addressed in an earlier beta. Please let us opt out of this behaviour or perhaps suggest a way to opt out of the auth0 client code executing during the build...? I assume the nextjs middleware is executing. All of our app pages are dynamic.

Unless I'm missing something this pattern of reusing a single build in different envs is quite common.

[robcaldecott]

This was a similar issue in a v4 beta.

#1849

I wonder if there is a similar API route being executed at build time. I will do some experiments.

We will stick with 4.4.0 for now.

[frederikprijck]

I do not think I am advocating against a single build and multiple environments. In contrary, a single build + multi environments is exactly what i would recommend but I do not understand how this relates to the topic.

Our SDK can not function without certain values, so we have added validation to enforce this, which is also not uncommon (e.g. see https://dev.to/austinshelby/you-are-reading-environment-variables-the-wrong-way-in-nextjs-45da).

I am not saying you should provide your actual configuration values in the pipeline. I am saying that our SDK doesn't work without the values in the first place, and we have now moved this validation to fail fast (at compilation) rather than only at run time, which does help with reporting configuration issues.

I don't understand why this change is necessary

Because the change in env variable naming in v4 has resulted in many people contacting us about the pain of the migration, and the fact that it is easy to miss configuring a certain env variable, and then the error is not clear about which is missing. Instead, we get random errors at places where the value is used, but does not exist (such as the issue u linked)

This was a similar issue in a v4 beta.

That one looks a bit different, in the sense that it has an uncaught error when it wasn't provided. Which is exactly what we want to avoid with what we are doing in 4.4.1.

[frederikprijck]

However, having talked about this internally, we are considering changing this to be a warning and not break.

Even though I believe an error is what we should be doing, I think this should have been like this from the beginning and this is a fair middleground.

[robcaldecott]

Ok, so how do you suggest we get our builds to work without using valid variables?

[frederikprijck]

Ok, so how do you suggest we get our builds to work without using valid variables?

By using placeholders. If the build worked without value, it should work with placeholders as we verify the existence, not the validity.

[robcaldecott]

Lovely, if empty strings as values will work then we can definitely accommodate that.

[ik-southpole]

First of all it was a breaking change for us, because obviously many build builds agnostic of environment variables with an idea to initialise Auth0Client in runtime with params passed via process.env. With update from v4.4.0 to v4.4.1, our builds start to fail. #2026 (comment)

[lukem1]

This broke builds for my team as well. I really don't think this validation check has much value in the context of a build. Supplying placeholder environment variables at build time has no bearing on whether or not they are being properly configured at run time.

Further, supplying run time secrets at build time is something that should be discouraged. And this validation actively encourages it. Many are going to assume the actual values are required, not just placeholders.

[frederikprijck]

I think it is a mistake to enforce the lack of runtime validation checks because you want to be able to instantiate the SDK without the required properties.

The root cause of the issue here isn't the validation we added, but the fact that the SDK is being instantiated without the required configuration and the solution is to:

• Ensure the configuration is provided
• Do not instantiate the SDK when the configuration isn't available.

That said, given the fact that this broke more people then we would have hoped for (and we should have had this check from the beginning, but we didn't so that is on us), we are going to go ahead and move this to be a warning. But I would still encourage to not rely on the behavior to be able to instantiate an SDK without providing the required configuration.

Closing this, as the PR to change to a warning will go out with the next release.