quarkusio/quarkus · error · RuntimeException

Invalid environment variable: ${envVar}

Error message

Invalid environment variable: ${envVar}

What it means

RunMojo's envVarsAsMap function converts the configured environment-variable list into a Map before launching the dev-mode process. Each entry must contain '=' (split with limit 2, so values may contain '='). Entries without an '=' separator throw RuntimeException 'Invalid environment variable: <envVar>'.

Source

Thrown at devtools/maven/src/main/java/io/quarkus/maven/RunMojo.java:160

                            .error().inherited();
                    if (workingDirectory != null) {
                        pb.directory(workingDirectory);
                    }
                    if ((environmentVariables != null) && !environmentVariables.isEmpty()) {
                        pb.environment(envVarsAsMap());
                    }
                    pb.run();
                }

                private Map<String, String> envVarsAsMap() {
                    String[] envVars = environmentVariables.split(",");
                    Map<String, String> env = new HashMap<>();
                    for (String envVar : envVars) {
                        String[] parts = envVar.split("=", 2);
                        if (parts.length == 2) {
                            env.put(parts[0], parts[1]);
                        } else {
                            throw new RuntimeException("Invalid environment variable: " + envVar);
                        }
                    }
                    return env;
                }
            },
                    RunCommandActionResultBuildItem.class.getName(), DevServicesLauncherConfigResultBuildItem.class.getName());
            if (target != null && !exists.get()) {
                getLog().error("quarkus.run.target " + target + " is not found");
                return;
            }
            if (tooMany.get() != null) {
                getLog().error(
                        "Too many installed extensions support quarkus:run.  Use -Dquarkus.run.target=<target> to choose");
                getLog().error("Extensions: " + tooMany.get());
            }
        } finally {
            // Clear all the system properties set by the plugin
            propertiesToClear.forEach(System::clearProperty);

View on GitHub (pinned to e1c734241f)

Solutions

1. Give every entry an explicit value: DEBUG=true instead of DEBUG
2. Remember values may contain '=' (split uses limit 2), so KEY=a=b is valid
3. Inherit/export variables in the shell instead of the mojo config if you don't want to set them here
4. Trim whitespace: KEY = true creates key 'KEY ' — write KEY=true

Example fix

<!-- before -->
<envVars>DEBUG,QUARKUS_LOG_LEVEL=DEBUG</envVars>
<!-- after -->
<envVars>DEBUG=true,QUARKUS_LOG_LEVEL=DEBUG</envVars>

// Validate env var entries before configuring quarkus:dev:
for (String e : envVars.split(",")) {
  if (!e.contains("=")) throw new IllegalArgumentException("Invalid environment variable: " + e);
}

try { runMojo.execute(); }
catch (RuntimeException e) {
  if (e.getMessage().startsWith("Invalid environment variable")) {
    log.error("Env var entries must be KEY=VALUE: {}", e.getMessage());
  } else throw e;
}

When it happens

Trigger: Configuring quarkus:dev `envVars` (or environmentVariables) with an entry lacking '=', e.g. <envVars>DEBUG</envVars> instead of DEBUG=true.

Common situations: Listing variable names expecting them to be inherited from the shell; copying shell `export FOO` syntax; typos dropping the '='; using spaces around the '=' which become part of the value.

Related errors

• Unable to parse pom file: ${pom}
• Could not resolve POM for
• Failed to log the dependency tree to a file
• Parameter 'mode' was set to '<mode>' while expected one of '
• Failed to resolve application model <appArtifact> dependenci

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/3e74991e01813810. Report an issue: GitHub.