pentaho/pentaho-kettle · error · KettleException

HTTP.Error.UnknownHostException

HTTP.Error.UnknownHostException

Error message

HTTP.Error.UnknownHostException

What it means

If the target hostname cannot be resolved to an IP address, callHttpService catches UnknownHostException and rethrows it as a KettleException with the HTTP.Error.UnknownHostException message containing the unresolvable host. DNS resolution failed before any HTTP request was made.

Solutions

1. Verify the hostname in the URL field resolves: nslookup/ping it from the machine running Pentaho
2. Fix typos or switch to an IP/parameterized variable per environment
3. Configure correct DNS servers or add the host to /etc/hosts
4. Ensure VPN or internal DNS is active when running the transformation on a server
5. Replace hard-coded hostnames with Kettle environment variables for portability

Example fix

// before
String url = "http://prod-api.internal.local/service"; // not resolvable here
// after
String url = getVariable( "API_HOST", "http://localhost:8080" ) + "/service";

// resolve host before running
try {
  InetAddress.getByName( new URL( realUrl ).getHost() );
} catch ( UnknownHostException e ) {
  throw new IllegalArgumentException( "Unresolvable host in HTTP step URL: " + realUrl, e );
}

try {
  transformation.execute( arguments );
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "UnknownHostException" ) ) {
    log.error( "DNS failure for host: {} — check DNS/VPN/hosts file", e.getMessage() );
  } else { throw e; }
}

When it happens

Trigger: callHttpService → executeMethod → HttpClient throws UnknownHostException because the URL's host has no DNS entry (or local resolution is broken).

Common situations: Typo in hostname; DNS server outage or misconfigured resolv.conf; hostname only resolvable on an internal DNS/VPN not active at runtime; /etc/hosts entry missing on the server running the transformation; environment-specific hostnames not parameterized per environment.

Related errors

• HTTP.Exception.IllegalStatusCode
• HTTP.Exception.Authentication
• HTTP.Exception.CouldnotFindField
• HTTP.Log.UnableGetResult
• HTTPPOST.Exception.IllegalStatusCode

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/http/HTTP.java:238

        }
        if ( !Utils.isEmpty( meta.getResponseTimeFieldName() ) ) {
          newRow = RowDataUtil.addValueData( newRow, returnFieldsOffset, new Long( responseTime ) );
          returnFieldsOffset++;
        }
        if ( !Utils.isEmpty( meta.getResponseHeaderFieldName() ) ) {
          newRow = RowDataUtil.addValueData( newRow, returnFieldsOffset, headerString );
        }

      } finally {
        if ( httpResponse != null ) {
          httpResponse.close();
        }
        // Release current connection to the connection pool once you are done
        method.releaseConnection();
      }
      return newRow;
    } catch ( UnknownHostException uhe ) {
      throw new KettleException( BaseMessages.getString( PKG, "HTTP.Error.UnknownHostException", uhe.getMessage() ) );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "HTTP.Log.UnableGetResult", uri ), e );
    }
  }

  private URIBuilder constructUrlBuilder( RowMetaInterface outputRowMeta, Object[] row ) throws KettleValueException,
    KettleException {
    URIBuilder uriBuilder;
    try {
      String baseUrl = data.realUrl;
      if ( meta.isUrlInField() ) {
        // get dynamic url
        baseUrl = outputRowMeta.getString( row, data.indexOfUrlField );
      }

      if ( isDetailed() ) {
        logDetailed( BaseMessages.getString( PKG, "HTTP.Log.Connecting", baseUrl ) );
      }

View on GitHub (pinned to f3058517a1)