{"record":{"id":"63c21fcaffc0a591","repo":"pentaho/pentaho-kettle","slug":"http-error-unknownhostexception","errorCode":"HTTP.Error.UnknownHostException","errorMessage":"HTTP.Error.UnknownHostException","messagePattern":"HTTP\\.Error\\.UnknownHostException","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/http/HTTP.java","lineNumber":238,"sourceCode":"        }\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\n      } finally {\n        if ( httpResponse != null ) {\n          httpResponse.close();\n        }\n        // Release current connection to the connection pool once you are done\n        method.releaseConnection();\n      }\n      return newRow;\n    } catch ( UnknownHostException uhe ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"HTTP.Error.UnknownHostException\", uhe.getMessage() ) );\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"HTTP.Log.UnableGetResult\", uri ), e );\n    }\n  }\n\n  private URIBuilder constructUrlBuilder( RowMetaInterface outputRowMeta, Object[] row ) throws KettleValueException,\n    KettleException {\n    URIBuilder uriBuilder;\n    try {\n      String baseUrl = data.realUrl;\n      if ( meta.isUrlInField() ) {\n        // get dynamic url\n        baseUrl = outputRowMeta.getString( row, data.indexOfUrlField );\n      }\n\n      if ( isDetailed() ) {\n        logDetailed( BaseMessages.getString( PKG, \"HTTP.Log.Connecting\", baseUrl ) );\n      }","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/http/HTTP.java#L220-L256","documentation":"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.","triggerScenarios":"callHttpService → executeMethod → HttpClient throws UnknownHostException because the URL's host has no DNS entry (or local resolution is broken).","commonSituations":"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.","solutions":["Verify the hostname in the URL field resolves: nslookup/ping it from the machine running Pentaho","Fix typos or switch to an IP/parameterized variable per environment","Configure correct DNS servers or add the host to /etc/hosts","Ensure VPN or internal DNS is active when running the transformation on a server","Replace hard-coded hostnames with Kettle environment variables for portability"],"exampleFix":"// before\nString url = \"http://prod-api.internal.local/service\"; // not resolvable here\n// after\nString url = getVariable( \"API_HOST\", \"http://localhost:8080\" ) + \"/service\";","handlingStrategy":"validation","validationCode":"// resolve host before running\ntry {\n  InetAddress.getByName( new URL( realUrl ).getHost() );\n} catch ( UnknownHostException e ) {\n  throw new IllegalArgumentException( \"Unresolvable host in HTTP step URL: \" + realUrl, e );\n}","typeGuard":null,"tryCatchPattern":"try {\n  transformation.execute( arguments );\n} catch ( KettleException e ) {\n  if ( e.getMessage().contains( \"UnknownHostException\" ) ) {\n    log.error( \"DNS failure for host: {} — check DNS/VPN/hosts file\", e.getMessage() );\n  } else { throw e; }\n}","preventionTips":["Parameterize hostnames with environment variables per environment","Verify DNS/VPN on the server that executes the transformation","Add critical hosts to /etc/hosts as a fallback","Test resolution with nslookup before scheduling jobs"],"tags":["kettle","pdi","http","dns","network"],"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"}