pentaho/pentaho-kettle · error · RuntimeException

undefined

Error message

${name} undefined

What it means

EnvironmentVariableGetter.getEnvVarible reads an environment variable with System.getenv and throws RuntimeException '<name> undefined' when the variable is not present in the process environment. It is a strict accessor that treats a missing env var as a hard failure.

Solutions

  1. Set the required environment variable before launching the JVM (export NAME=value or container env config).
  2. Fix the variable name spelling/case in the calling code to match what is defined.
  3. If the variable is optional, read System.getenv directly and handle null instead of using this strict getter.
  4. Add the variable to the deployment/runtime configuration so all environments define it.

Example fix

// before
String v = new EnvironmentVariableGetter().getEnvVarible( "BUILD_NUMBER" );
// after
String v = System.getenv( "BUILD_NUMBER" );
if ( v == null ) { v = "0"; } // or fail with a clear message
Defensive patterns

Strategy: validation

Validate before calling

String v = System.getenv( name );
if ( v == null ) { v = defaultValue; } // or abort with a clear config error before calling the getter

Type guard

Optional<String> envOrEmpty( String name ) {
  return Optional.ofNullable( System.getenv( name ) );
}

Try / catch

try {
  String v = new EnvironmentVariableGetter().getEnvVarible( name );
} catch ( RuntimeException e ) {
  log.error( "Required environment variable missing: " + name );
}

Prevention

When it happens

Trigger: Calling getEnvVarible(name) where System.getenv(name) returns null — the variable was never set, was unset before the process started, or its name is misspelled/case-mismatched.

Common situations: Running the app locally without the CI/build environment variables set (e.g. build-version related vars); Docker/Kubernetes containers missing an env entry; case sensitivity differences between Windows and Linux.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/0fe304cc5957afe5. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/version/EnvironmentVariableGetter.java:21

 * Pentaho
 *
 * Copyright (C) 2024 - 2026 by Pentaho Canada Inc. : http://www.pentaho.com
 *
 * Use of this software is governed by the Business Source License included
 * in the LICENSE.TXT file.
 *
 * Change Date: 2030-06-15
 ******************************************************************************/



package org.pentaho.di.version;

public class EnvironmentVariableGetter {
  public String getEnvVarible( String name ) throws Exception {
    String result = System.getenv( name );
    if ( result == null ) {
      throw new RuntimeException( name + " undefined" );
    }
    return result;
  }
}

View on GitHub (pinned to f3058517a1)