pentaho/pentaho-kettle · error · KettleException

HTTPPOST.Error.UnknownHostException

Error message

HTTPPOST.Error.UnknownHostException

What it means

HTTPPOST step wraps java.net.UnknownHostException in a KettleException with message 'HTTPPOST.Error.UnknownHostException'. It is thrown from callHTTPPOST when the JVM cannot resolve the hostname of the target URL to an IP address during the POST request. Unlike the generic catch below, it indicates a DNS/hostname problem rather than an HTTP problem.

Solutions

  1. Verify the hostname in the URL (URL-in-field value or step URL setting) resolves: nslookup/ping the host from the machine running the transformation.
  2. Correct typos in the hostname and ensure the scheme/host syntax of the URL is valid.
  3. Add the host to /etc/hosts or configure DNS (resolv.conf, VPC DNS) so the name resolves.
  4. Retry the transformation if DNS was transiently unavailable.

Example fix

// before
String url = "http://servr01.internal.local:8080/api";
// after
String url = "http://server01.internal.local:8080/api"; // hostname spelled correctly and resolvable
Defensive patterns

Strategy: retry

Validate before calling

// Pre-flight DNS check before running the transformation
InetAddress a = InetAddress.getByName("server01.internal.local");
System.out.println("Resolved: " + a.getHostAddress());

Type guard

boolean isResolvable(String host) {
  try { InetAddress.getByName(host); return true; }
  catch (UnknownHostException e) { return false; }
}

Try / catch

try {
  result = callHttpPost(url, params);
} catch (KettleException ke) {
  if (String.valueOf(ke.getMessage()).contains("UnknownHostException")) {
    // DNS failure: alert ops, optionally retry with backoff
  } else { throw ke; }
}

Prevention

When it happens

Trigger: callHTTPPOST (invoked from outputRowData) executes an HttpClient call whose data.realUrl host cannot be resolved by DNS; java throws UnknownHostException, caught by the dedicated catch (UnknownHostException uhe) block at line 321.

Common situations: Typo in hostname in the URL field or static URL; internal hostname used from a machine without access to internal DNS; DNS server outage; missing /etc/hosts entry in a container; transient DNS failure on Kubernetes pods.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/httppost/HTTPPOST.java:322

          returnFieldsOffset++;
        }
        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 {
        // Release current connection to the connection pool once you are done
        post.releaseConnection();
        if ( httpResponse != null ) {
          httpResponse.close();
        }
      }
      return newRow;
    } catch ( UnknownHostException uhe ) {
      throw new KettleException( BaseMessages.getString( PKG,
        "HTTPPOST.Error.UnknownHostException", uhe.getMessage() ) );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "HTTPPOST.Error.CanNotReadURL", data.realUrl ), e );

    } finally {
      if ( fis != null ) {
        BaseStep.closeQuietly( fis );
      }
    }
  }

  protected int requestStatusCode( HttpResponse httpResponse ) {
    return httpResponse.getStatusLine().getStatusCode();
  }

  protected InputStreamReader openStream( String encoding, HttpResponse httpResponse ) throws Exception {
    if ( !Utils.isEmpty( encoding ) ) {
      return new InputStreamReader( httpResponse.getEntity().getContent(), encoding );

View on GitHub (pinned to f3058517a1)