pentaho/pentaho-kettle · error · KettleStepException

HTTP.Exception.IllegalStatusCode

HTTP.Exception.IllegalStatusCode

Error message

HTTP.Exception.IllegalStatusCode

What it means

When the HTTP response status code cannot be determined (statusCode == -1, typically meaning no valid response was received), callHttpService throws this KettleStepException for the target URL. It indicates a broken connection or protocol failure rather than a real HTTP status.

Solutions

1. Verify the server is reachable and serving HTTP on that URL/port
2. Test with curl -v to see connection/TLS errors directly
3. Check TLS: add the server certificate to the JVM truststore or correct the protocol (http vs https)
4. Fix proxy/firewall rules that drop or reset the connection
5. Confirm the URL points at an HTTP endpoint, not another protocol

Example fix

// before
String realUrl = "ftp://host/file"; // non-HTTP endpoint → status -1
// after
String realUrl = "https://host/api/file";

// preflight reachability
InetAddress addr = InetAddress.getByName( host );
try ( Socket s = new Socket() ) { s.connect( new InetSocketAddress( addr, port ), 5000 ); }

int attempts = 0;
while ( attempts < 3 ) {
  try { runTransformation(); break; }
  catch ( KettleStepException e ) {
    if ( e.getMessage().contains( "IllegalStatusCode" ) && ++attempts < 3 ) {
      Thread.sleep( 2000L * attempts ); continue; // transient connection failure
    } throw e;
  }
}

When it happens

Trigger: callHttpService's switch hits case -1: the request failed to produce a status line — connection dropped, TLS handshake failure, or the executeMethod returned without a valid response.

Common situations: Target server closed the connection prematurely; SSL/TLS version or certificate mismatch; hostname resolves but nothing listening; firewall silently dropping the request; malformed response from a non-HTTP service on that port.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• HTTP.Error.UnknownHostException
• HTTP.Exception.Authentication
• HTTP.Exception.CouldnotFindField
• HTTP.Log.UnableGetResult
• HTTPPOST.Exception.IllegalStatusCode

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/http/HTTP.java:177

        }
        // calculate the responseTime
        long responseTime = System.currentTimeMillis() - startTime;
        if ( log.isDetailed() ) {
          log.logDetailed( BaseMessages.getString( PKG, "HTTP.Log.ResponseTime", responseTime, uri ) );
        }
        int statusCode = requestStatusCode( httpResponse );
        // The status code
        if ( isDebug() ) {
          logDebug( BaseMessages.getString( PKG, "HTTP.Log.ResponseStatusCode", "" + statusCode ) );
        }

        String body;
        switch ( statusCode ) {
          case HttpURLConnection.HTTP_UNAUTHORIZED:
            throw new KettleStepException( BaseMessages
              .getString( PKG, "HTTP.Exception.Authentication", data.realUrl ) );
          case -1:
            throw new KettleStepException( BaseMessages
              .getString( PKG, "HTTP.Exception.IllegalStatusCode", data.realUrl ) );
          case HttpURLConnection.HTTP_NO_CONTENT:
            body = "";
            break;
          default:
            HttpEntity entity = httpResponse.getEntity();
            if ( entity != null ) {
              body = StringUtils.isEmpty( meta.getEncoding() ) ? EntityUtils.toString( entity ) : EntityUtils.toString( entity, meta.getEncoding() );
            } else {
              body = "";
            }
            break;
        }

        Header[] headers = searchForHeaders( httpResponse );

        JSONObject json = new JSONObject();
        for ( Header header : headers ) {

View on GitHub (pinned to f3058517a1)