Troubleshooting NGINX

Tier: Free, Premium, Ultimate Offering: Self-managed

When configuring NGINX, you might encounter the following issues.

Error: 400 Bad Request: too many Host headers

The workaround is to make sure you don’t have the proxy_set_header configuration in nginx['custom_gitlab_server_config'] settings. Instead, use the proxy_set_headers configuration in your gitlab.rb file.

Error: Received fatal alert: handshake_failure

You might get an error that states: 

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure

This issue occurs when you use an older Java-based IDE client to interact with your GitLab instance. Those IDEs can use the TLS 1 protocol, which the Linux package installations don’t support by default.

To resolve this issue, upgrade ciphers on your server, similar to the user in issue 624.

If it is not possible to make this server change, you can default back to the old behavior by changing the values in your /etc/gitlab/gitlab.rb: 

nginx['ssl_protocols'] = "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"

Mismatch between private key and certificate

In the NGINX logs, you might find: 

x509 certificate routines:X509_check_private_key:key values mismatch)

This issue occurs when there is a mismatch between your private key and certificate.

To resolve this, match the correct private key with your certificate:

  1. To ensure you have the correct key and certificate, check whether the moduli of the private key and certificate match: 

    /opt/gitlab/embedded/bin/openssl rsa -in /etc/gitlab/ssl/gitlab.example.com.key -noout -modulus | /opt/gitlab/embedded/bin/openssl sha256

/opt/gitlab/embedded/bin/openssl x509 -in /etc/gitlab/ssl/gitlab.example.com.crt -noout -modulus| /opt/gitlab/embedded/bin/openssl sha256

  2. After you verify that they match, reconfigure and reload NGINX: 

    sudo gitlab-ctl reconfigure
sudo gitlab-ctl hup nginx

Request Entity Too Large

In the NGINX logs, you might find: 

Request Entity Too Large

This issue occurs when you have increased the max import size.

To resolve this, increase the client max body size.

In a Kubernetes-based GitLab installation, this setting is named differently.

To increase the value of client_max_body_size:

  1. Edit /etc/gitlab/gitlab.rb and set the preferred value: 

    nginx['client_max_body_size'] = '250m'
  2. Save the file and reconfigure GitLab.

  3. HUP NGINX to cause it to reload with the updated configuration gracefully: 

    sudo gitlab-ctl hup nginx

Security scan warning: NGINX HTTP Server Detection

This issue occurs when some security scanners detect the Server: nginx HTTP header. Most scanners with this alert mark it as Low or Info severity. For example, see Nessus.

You should ignore this warning, as the benefit of removing the header is low, and its presence helps support the NGINX project in usage statistics.

The workaround is to turn the header off by using hide_server_tokens:

  1. Edit /etc/gitlab/gitlab.rb and set the value: 

    nginx['hide_server_tokens'] = 'on'
  2. Save the file and reconfigure GitLab.

  3. HUP NGINX to cause it to reload with the updated configuration gracefully: 

    sudo gitlab-ctl hup nginx

Branch not found when using Web IDE and external NGINX

You might get an error that states: 

Branch 'branch_name' was not found in this project's repository

This issue occurs when there’s a trailing slash in proxy_pass in your NGINX configuration file.

To resolve it:

  1. Edit your NGINX configuration file so there’s no trailing slash in proxy_pass: 

    proxy_pass https://1.2.3.4;

  2. Restart NGINX: 

    sudo systemctl restart nginx

Error: worker_connections are not enough

You might get 502 errors from GitLab, and find the following in NGINX logs: 

worker_connections are not enough

This issue occurs when worker connections are set to a value that’s too low.

To resolve it, configure the NGINX worker connections to a higher value:

  1. Edit /etc/gitlab/gitlab.rb: 

    gitlab['nginx']['worker_connections'] = 10240

    10240 connections is the default value.

  2. Save the file and reconfigure GitLab for the changes to take effect.