{"record":{"id":"81151b996ea63456","repo":"pentaho/pentaho-kettle","slug":"httppost-error-unknownhostexception","errorCode":null,"errorMessage":"HTTPPOST.Error.UnknownHostException","messagePattern":"HTTPPOST\\.Error\\.UnknownHostException","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/httppost/HTTPPOST.java","lineNumber":322,"sourceCode":"          returnFieldsOffset++;\n        }\n        if ( !Utils.isEmpty( meta.getResponseTimeFieldName() ) ) {\n          newRow = RowDataUtil.addValueData( newRow, returnFieldsOffset, new Long( responseTime ) );\n          returnFieldsOffset++;\n        }\n        if ( !Utils.isEmpty( meta.getResponseHeaderFieldName() ) ) {\n          newRow = RowDataUtil.addValueData( newRow, returnFieldsOffset, headerString );\n        }\n      } finally {\n        // Release current connection to the connection pool once you are done\n        post.releaseConnection();\n        if ( httpResponse != null ) {\n          httpResponse.close();\n        }\n      }\n      return newRow;\n    } catch ( UnknownHostException uhe ) {\n      throw new KettleException( BaseMessages.getString( PKG,\n        \"HTTPPOST.Error.UnknownHostException\", uhe.getMessage() ) );\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"HTTPPOST.Error.CanNotReadURL\", data.realUrl ), e );\n\n    } finally {\n      if ( fis != null ) {\n        BaseStep.closeQuietly( fis );\n      }\n    }\n  }\n\n  protected int requestStatusCode( HttpResponse httpResponse ) {\n    return httpResponse.getStatusLine().getStatusCode();\n  }\n\n  protected InputStreamReader openStream( String encoding, HttpResponse httpResponse ) throws Exception {\n    if ( !Utils.isEmpty( encoding ) ) {\n      return new InputStreamReader( httpResponse.getEntity().getContent(), encoding );","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/httppost/HTTPPOST.java#L304-L340","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Correct typos in the hostname and ensure the scheme/host syntax of the URL is valid.","Add the host to /etc/hosts or configure DNS (resolv.conf, VPC DNS) so the name resolves.","Retry the transformation if DNS was transiently unavailable."],"exampleFix":"// before\nString url = \"http://servr01.internal.local:8080/api\";\n// after\nString url = \"http://server01.internal.local:8080/api\"; // hostname spelled correctly and resolvable","handlingStrategy":"retry","validationCode":"// Pre-flight DNS check before running the transformation\nInetAddress a = InetAddress.getByName(\"server01.internal.local\");\nSystem.out.println(\"Resolved: \" + a.getHostAddress());","typeGuard":"boolean isResolvable(String host) {\n  try { InetAddress.getByName(host); return true; }\n  catch (UnknownHostException e) { return false; }\n}","tryCatchPattern":"try {\n  result = callHttpPost(url, params);\n} catch (KettleException ke) {\n  if (String.valueOf(ke.getMessage()).contains(\"UnknownHostException\")) {\n    // DNS failure: alert ops, optionally retry with backoff\n  } else { throw ke; }\n}","preventionTips":["Use FQDNs, avoid stale short names","Verify DNS resolution from the runtime host pre-deploy","Maintain /etc/hosts entries in containers for internal services","Monitor DNS health in the cluster"],"tags":["network","dns","http-post","hostname-resolution"],"backgroundTag":"network-request-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"}