pentaho/pentaho-kettle · error · KettleStepException

WebServices.ERROR0013.UnknownHost

WebServices.ERROR0013.UnknownHost

Error message

WebServices.ERROR0013.UnknownHost

What it means

Thrown by WebService.requestSOAP() when java.net.UnknownHostException is raised while resolving the SOAP endpoint's hostname — i.e., DNS lookup failed. The step wraps it in a KettleStepException with message key WebServices.ERROR0013.UnknownHost including the service URL. This is a DNS/network reachability problem, not a step configuration parse issue.

Solutions

  1. Verify the hostname resolves: nslookup/ping the host from the machine running Pentaho
  2. Correct the URL in the step dialog (typos, wrong internal vs external hostname)
  3. Fix DNS/VPN/network configuration or add a hosts-file entry for the environment
  4. Use an IP or a resolvable FQDN if short names are not configured in search domains

Example fix

// before
// URL: http://internalws:8080/service  (UnknownHostException on VM)
// after
// URL: http://internalws.corp.example.com:8080/service
// or add '10.0.0.42 internalws' to /etc/hosts on the Pentaho server.
Defensive patterns

Strategy: retry

Validate before calling

// pre-flight DNS check before running the transformation
InetAddress addr = InetAddress.getByName( host );
// throws UnknownHostException early with a clearer message
if ( addr == null ) {
  throw new IllegalStateException( "Host not resolvable: " + host );
}

Try / catch

try {
  trans.execute( null );
} catch ( KettleStepException e ) {
  if ( e.getMessage() != null && e.getMessage().contains( "ERROR0013" ) ) {
    logError( "Cannot resolve SOAP host " + serviceUrl + ": check DNS/VPN/hosts file" );
    // optionally retry after network remediation
  }
}

Prevention

When it happens

Trigger: requestSOAP() POSTs to cachedURLService whose host cannot be resolved by the JVM's DNS resolver, throwing UnknownHostException caught by the dedicated catch clause.

Common situations: Hostname typo in the step URL, running on a machine/cluster without access to the internal DNS zone, VPN not connected, Docker/K8s container lacking DNS config, or hostname removed from DNS after a server migration.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/webservices/WebService.java:399

        httpEntity = httpResponse.getEntity();
        ContentType contentType = ContentType.getOrDefault( httpEntity );
        charSet = contentType.getCharset();
        processRows( httpEntity.getContent(), rowData, rowMeta, cachedWsdl.getWsdlTypes()
          .isElementFormQualified( cachedWsdl.getTargetNamespace() ), charSet.toString() );
      } else if ( responseCode == HttpStatus.SC_UNAUTHORIZED ) {
        throw new KettleStepException( BaseMessages.getString( PKG, "WebServices.ERROR0011.Authentication",
          cachedURLService ) );
      } else if ( responseCode == HttpStatus.SC_NOT_FOUND ) {
        throw new KettleStepException( BaseMessages.getString( PKG,
          "WebServices.ERROR0012.NotFound", cachedURLService ) );
      } else {
        throw new KettleStepException( BaseMessages.getString( PKG,
          "WebServices.ERROR0001.ServerError", Integer.toString( responseCode ),
          Const.NVL( new String( EntityUtils.toString( httpEntity, charSet.toString() ) ), "" ), cachedURLService ) );
      }
      // requestTime += Const.nanoTime() - currentRequestTime;
    } catch ( UnknownHostException e ) {
      throw new KettleStepException( BaseMessages
        .getString( PKG, "WebServices.ERROR0013.UnknownHost", cachedURLService ), e );
    } catch ( IOException e ) {
      throw new KettleStepException( BaseMessages
        .getString( PKG, "WebServices.ERROR0005.IOException", cachedURLService ), e );
    } catch ( URISyntaxException e ) {
      throw new KettleStepException( BaseMessages.getString( PKG, "WebServices.ERROR0002.InvalidURI",
        cachedURLService ), e );
    } finally {
      data.argumentRows.clear(); // ready for the next batch.
      if ( vHttpMethod != null ) {
        vHttpMethod.releaseConnection();
      }
    }
  }

  private void initWsdlEnv() throws KettleException {
    if ( meta.equals( cachedMeta ) ) {
      return;

View on GitHub (pinned to f3058517a1)