Analysis and Solutions for Tomcat 7.0.43 HTTP Request Header Parsing Errors

Problem Background and Symptom Description

During the Tomcat version upgrade process from 7.0.42 to 7.0.43, developers frequently encounter HTTP request header parsing errors. Specifically, in WebSocket application scenarios, server logs show "Error parsing HTTP request header" warnings, while client browser consoles display "Unrecognized frame opcode: 5" errors.

Below is a typical problem scenario code example:

// Server-side error log example
Sep 16, 2013 3:08:34 AM org.apache.coyote.http11.AbstractHttp11Processor process
INFO: Error parsing HTTP request header
Note: further occurrences of HTTP header parsing errors will be logged at DEBUG level.

The corresponding client error message is:

// Browser console error
WebSocket connection to 'ws://www.testapp.com/socket/notification/848df2e62fcf93e1b3?X-Atmosphere-tracking-i...Date=0&Content-Type=application/json;%20charset=UTF-8&X-atmo-protocol=true' failed: Unrecognized frame opcode: 5

Core Problem Analysis

Through in-depth analysis, the root cause primarily lies in changes to the APR (Apache Portable Runtime) connector handling mechanism in Tomcat 7.0.43. In previous versions, APR listener configuration might not cause significant compatibility issues, but in version 7.0.43, such configuration conflicts become more apparent.

The key configuration issue appears in the server.xml file:

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on"/>

When using the APR connector while simultaneously configuring a keystore for SSL/TLS encryption, configuration conflicts arise. The APR connector uses the native OpenSSL library for encrypted communication, whereas the standard Java connector employs Java's keystore mechanism. These two mechanisms cannot operate concurrently in Tomcat 7.0.43.

Primary Solutions

Solution 1: Remove APR Listener Configuration

This is the most direct and effective solution. In the server.xml configuration file, locate and comment out or delete the APR listener configuration line:

// Configuration before modification
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on"/>

// Configuration after modification
<!-- <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on"/> -->

After modification, restart the Tomcat server for the changes to take effect. The advantage of this method is its simplicity and directness, requiring no application code changes—only server configuration adjustments.

Solution 2: Check Protocol Configuration

Another common issue is incorrect protocol configuration. Developers might inadvertently use HTTPS protocol to access a server configured only for HTTP:

// Incorrect access method
WebSocket connection to 'wss://localhost:8080/websocket'

// Correct access method  
WebSocket connection to 'ws://localhost:8080/websocket'

Ensuring that the client uses the same protocol as configured on the server side can prevent parsing errors due to protocol mismatches.

Supplementary Solutions

HTTP Header Size Adjustment

In some cases, excessively large HTTP request headers can also cause parsing errors. This can be resolved by adjusting the maxHttpHeaderSize attribute of the Connector:

<Connector port="8080" protocol="HTTP/1.1"
           maxHttpHeaderSize="1048576"
           ...other configurations.../>

Setting maxHttpHeaderSize to a larger value (e.g., 1048576 bytes, or 1MB) can accommodate larger HTTP header data.

Cookie Cache Cleanup

Excessive cached cookies may cause HTTP request headers to exceed default limits. Regularly clearing browser cookies or implementing server-side cookie management strategies can effectively prevent such issues.

In-Depth Technical Principle Analysis

Tomcat 7.0.43 introduced enhancements in security and stability for HTTP request parsing. Significant differences exist between the APR connector and the standard Java connector at the implementation level:

• The APR connector utilizes native code and operating system-level optimizations
• The standard Java connector is entirely based on Java NIO implementation
• The two connectors differ in SSL/TLS handling, memory management, and threading models

When both APR listener and keystore configurations are present, Tomcat attempts to use two different encryption mechanisms, leading to internal state confusion and request parsing failures. The WebSocket protocol cannot establish connections properly in this environment, resulting in "Unrecognized frame opcode" errors.

Best Practice Recommendations

Based on the thorough analysis of Tomcat 7.0.43 issues, we recommend that developers adhere to the following best practices:

1. Explicitly choose to use either the APR connector or the standard Java connector in production environments, avoiding mixed configurations
2. Regularly inspect server logs to promptly identify and resolve configuration issues
3. Thoroughly test all functional modules for compatibility before version upgrades
4. Establish comprehensive monitoring mechanisms to detect WebSocket connection status in real-time
5. Maintain version consistency for Tomcat and related dependency libraries

By following these practices, similar problems can be effectively avoided, ensuring stable operation of web applications.