{"record":{"id":"62877a82282c52bb","repo":"pentaho/pentaho-kettle","slug":"webservices-error0013-unknownhost","errorCode":"WebServices.ERROR0013.UnknownHost","errorMessage":"WebServices.ERROR0013.UnknownHost","messagePattern":"WebServices\\.ERROR0013\\.UnknownHost","errorType":"error_code","errorClass":"KettleStepException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/webservices/WebService.java","lineNumber":399,"sourceCode":"        httpEntity = httpResponse.getEntity();\n        ContentType contentType = ContentType.getOrDefault( httpEntity );\n        charSet = contentType.getCharset();\n        processRows( httpEntity.getContent(), rowData, rowMeta, cachedWsdl.getWsdlTypes()\n          .isElementFormQualified( cachedWsdl.getTargetNamespace() ), charSet.toString() );\n      } else if ( responseCode == HttpStatus.SC_UNAUTHORIZED ) {\n        throw new KettleStepException( BaseMessages.getString( PKG, \"WebServices.ERROR0011.Authentication\",\n          cachedURLService ) );\n      } else if ( responseCode == HttpStatus.SC_NOT_FOUND ) {\n        throw new KettleStepException( BaseMessages.getString( PKG,\n          \"WebServices.ERROR0012.NotFound\", cachedURLService ) );\n      } else {\n        throw new KettleStepException( BaseMessages.getString( PKG,\n          \"WebServices.ERROR0001.ServerError\", Integer.toString( responseCode ),\n          Const.NVL( new String( EntityUtils.toString( httpEntity, charSet.toString() ) ), \"\" ), cachedURLService ) );\n      }\n      // requestTime += Const.nanoTime() - currentRequestTime;\n    } catch ( UnknownHostException e ) {\n      throw new KettleStepException( BaseMessages\n        .getString( PKG, \"WebServices.ERROR0013.UnknownHost\", cachedURLService ), e );\n    } catch ( IOException e ) {\n      throw new KettleStepException( BaseMessages\n        .getString( PKG, \"WebServices.ERROR0005.IOException\", cachedURLService ), e );\n    } catch ( URISyntaxException e ) {\n      throw new KettleStepException( BaseMessages.getString( PKG, \"WebServices.ERROR0002.InvalidURI\",\n        cachedURLService ), e );\n    } finally {\n      data.argumentRows.clear(); // ready for the next batch.\n      if ( vHttpMethod != null ) {\n        vHttpMethod.releaseConnection();\n      }\n    }\n  }\n\n  private void initWsdlEnv() throws KettleException {\n    if ( meta.equals( cachedMeta ) ) {\n      return;","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/webservices/WebService.java#L381-L417","documentation":"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.","triggerScenarios":"requestSOAP() POSTs to cachedURLService whose host cannot be resolved by the JVM's DNS resolver, throwing UnknownHostException caught by the dedicated catch clause.","commonSituations":"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.","solutions":["Verify the hostname resolves: nslookup/ping the host from the machine running Pentaho","Correct the URL in the step dialog (typos, wrong internal vs external hostname)","Fix DNS/VPN/network configuration or add a hosts-file entry for the environment","Use an IP or a resolvable FQDN if short names are not configured in search domains"],"exampleFix":"// before\n// URL: http://internalws:8080/service  (UnknownHostException on VM)\n// after\n// URL: http://internalws.corp.example.com:8080/service\n// or add '10.0.0.42 internalws' to /etc/hosts on the Pentaho server.","handlingStrategy":"retry","validationCode":"// pre-flight DNS check before running the transformation\nInetAddress addr = InetAddress.getByName( host );\n// throws UnknownHostException early with a clearer message\nif ( addr == null ) {\n  throw new IllegalStateException( \"Host not resolvable: \" + host );\n}","typeGuard":null,"tryCatchPattern":"try {\n  trans.execute( null );\n} catch ( KettleStepException e ) {\n  if ( e.getMessage() != null && e.getMessage().contains( \"ERROR0013\" ) ) {\n    logError( \"Cannot resolve SOAP host \" + serviceUrl + \": check DNS/VPN/hosts file\" );\n    // optionally retry after network remediation\n  }\n}","preventionTips":["Use fully-qualified hostnames rather than short names","Verify DNS resolution from the Pentaho server itself (nslookup) before scheduling","Keep VPN/DNS configuration valid on all execution nodes","Add hosts-file entries as a documented fallback for critical services"],"tags":["dns","network","hostname","soap"],"backgroundTag":"dns-resolution-failed","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}