"502: Bad Gateway" or "400: Request Header too large" errors when browsing TeamCity UI

Symptoms

1. Users encounter 400: Request Header too large or 502: Bad Gateway errors when browsing the TeamCity UI.
2. <TeamCity Server Home>/logs/catalina.{date}.log files contain errors similar to: org.apache.coyote.http11.Http11Processor.service Error parsing HTTP request header java.lang.IllegalArgumentException: Request header is too large

Cause

The most probable and common cause is the request header size exceeding the configured limit. There are two cases to consider:

1. TeamCity's built-in HTTPS settings (Administration > HTTPS Settings) are not used, meaning the TeamCity server is not using HTTPS at all, or HTTPS is configured on the reverse-proxy's side.

   • The current limit can be found in <TeamCity Server Home>/conf/server.xml file. It is the value (in bytes) of the maxHttpHeaderSize property of the active <Connector>.
   • The default value defined in server.xml is 16000 bytes.
   • If this property is not defined, then it defaults to 4096 bytes, which is Tomcat's default.

2. TeamCity's built-in HTTPS settings (Administration > HTTPS Settings) are configured. HTTPS settings configured in the TeamCity UI affect the built-in Tomcat server configuration directly, and they use a separate HTTPS connector.

   • The size limit can be defined by teamcity.https.maxHttpHeaderSize.bytes internal property.
   • If the above property is not defined, the default value 8192 is used.

To confirm whether the errors are indeed caused by a large request header, it is recommended to inspect the affected header in the browser developer console and verify whether it exceeds the specified limit.

Resolution

The limit can be easily increased:

1. If TeamCity's built-in HTTPS settings (Administration > HTTPS Settings) are not used, by changing (or adding) the maxHttpHeaderSize property of the active <Connector> in <TeamCity Server Home>/conf/server.xml file.
2. If TeamCity's built-in HTTPS settings (Administration > HTTPS Settings) are configured, by changing (or adding) the teamcity.https.maxHttpHeaderSize.bytes internal property.

For example, the value 65536 will increase the limit to 64KB.

The TeamCity server must be restarted in both cases for changes to take effect.

Additional information

HTTPS: Support custom maxHttpHeaderSize for connector