Fixing CERTIFICATE_VERIFY_FAILED In OpenHands With Self-Hosted GitLab

Nov 10, 2025 by Admin 70 views

Hey folks, if you're like me, you love the idea of running your own GitLab instance. It gives you so much control! However, sometimes things can get a little… tricky. That’s exactly what happened when I was setting up OpenHands with a self-hosted GitLab instance. Specifically, I ran into the dreaded CERTIFICATE_VERIFY_FAILED error. Let's dive in and fix this, shall we? This error pops up when OpenHands tries to talk to your GitLab server, but it doesn't trust the SSL certificate. This usually happens when you're using a self-signed certificate or one that isn't issued by a trusted Certificate Authority (CA). Don’t worry; we'll break down the issue and get it sorted. The issue is due to OpenHands, by default, not trusting the SSL certificate of your self-hosted GitLab instance. This typically happens when using self-signed certificates or certificates issued by a private CA. The steps below will help you to fix the problem.

Understanding the `CERTIFICATE_VERIFY_FAILED` Error

First, let's understand what's happening. When OpenHands tries to connect to your GitLab, it checks the certificate to make sure it's valid and issued by a trusted source. If the certificate isn't trusted (because it's self-signed or from a private CA), the verification fails, and you get the CERTIFICATE_VERIFY_FAILED error. The error message clearly indicates that the verification of the SSL certificate has failed. This usually arises when the certificate isn't recognized or trusted by the system.

Here’s a breakdown of the typical scenario:

Self-Signed Certificates: These are certificates you generate yourself. While easy to create, they aren't trusted by default by most systems. They lack the credibility of a certificate issued by a trusted Certificate Authority.
Private CA Certificates: If you're using a private Certificate Authority (CA) within your organization, OpenHands might not have the CA's certificate in its trust store. Therefore, it can't verify the GitLab certificate.

To fix this, you need to tell OpenHands to trust your GitLab's certificate. This can be done in a few ways, depending on your setup. Let's get to the fixes. The issue stems from OpenHands not inherently trusting the SSL certificate of your GitLab instance, especially if it's a self-hosted one. This lack of trust results in a CERTIFICATE_VERIFY_FAILED error, which essentially blocks communication between OpenHands and GitLab.

The Problem in Detail

The root cause lies in how OpenHands, and the underlying Python libraries it uses, handle SSL certificate verification. The error typically manifests when the certificate presented by your GitLab server is:

Not signed by a publicly trusted Certificate Authority (CA): This is the case with self-signed certificates or certificates issued by a private CA.
The CA that signed your certificate is not in the system's trust store: OpenHands needs to know and trust the CA to validate the certificate.

Basically, the program doesn't inherently trust the certificate from your GitLab instance, causing the verification process to fail.

Troubleshooting Steps and Solutions

Now, let's troubleshoot and fix this issue. Here are some strategies to overcome the CERTIFICATE_VERIFY_FAILED error when integrating OpenHands with a self-hosted GitLab instance. The core problem is that OpenHands doesn't trust the SSL certificate of your GitLab instance. Here’s what you can do:

1. Bypass SSL Verification (Not Recommended for Production)

This is the quickest fix to get things working, but it's generally not recommended for production environments because it disables security. You can bypass SSL verification by setting environment variables during the Docker run command. Setting the GIT_SSL_NO_VERIFY=true and PYTHONHTTPSVERIFY=0 environment variables disables SSL certificate verification. While this allows OpenHands to connect, it leaves your connection vulnerable to man-in-the-middle attacks. This approach disables SSL certificate verification, allowing OpenHands to connect without validating the certificate. It is a quick fix, especially when first setting up, but it is not recommended for production environments.

Here's how you'd modify your Docker run command:

docker run -it --rm \
  -e OLLAMA_BASE_URL="${OLLAMA_BASE_URL}" \
  -e PYTHONHTTPSVERIFY=0 \
  -e GIT_SSL_NO_VERIFY=true \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.openhands.dev/openhands/runtime:latest-nikolaik \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /home/debian/.openhands:/.openhands \
  --name openhands-app-manual \
  --network host \
  docker.openhands.dev/openhands/openhands:latest

Important: Use this only for testing and development. For production, proceed with the methods below.

2. Trust the Certificate (Recommended)

The best way to solve this is to make sure OpenHands trusts the SSL certificate of your GitLab instance.

A. Adding the Certificate to the System Trust Store:

First, you'll need to get the certificate for your GitLab instance. You can usually download it from your web browser (look for the lock icon in the address bar). Export the certificate in PEM format. The exported certificate should be in PEM format, and this file will be crucial for the next steps.
Next, copy the certificate file to your OpenHands container or the host machine where Docker is running. Copy the PEM-formatted certificate file to the appropriate directory.
Now, import the certificate into the system’s trust store. The exact command depends on your operating system. For Debian/Ubuntu, it is:
```
sudo cp your_gitlab_certificate.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates
```
If you're using Docker, you'll need to build a custom image that includes the certificate. Add the certificate to your base Docker image during the build process.
1. Create a Dockerfile: In the same directory as your docker-compose.yml or your OpenHands Dockerfile, create a new file named Dockerfile.
```
FROM docker.openhands.dev/openhands/openhands:latest
COPY your_gitlab_certificate.pem /usr/local/share/ca-certificates/
RUN update-ca-certificates
```
2. Build the Image: Build the custom Docker image. Replace <your-image-name> and <your-tag> with your preferred image name and tag.
```
docker build -t <your-image-name>:<your-tag> .
```
3. Update Your Docker Compose: Update your docker-compose.yml to use this new image.
```
version: "3.9"
services:
  openhands:
    image: <your-image-name>:<your-tag>
    # ... other configurations ...
```
Now, your OpenHands container will trust your GitLab certificate.

B. Using Environment Variables (Less Common, but Useful)

You can also set the NODE_EXTRA_CA_CERTS environment variable to point to your certificate file. Although, It is less straightforward than the above method.

3. Verify Your GitLab Configuration

Ensure that your GitLab instance is correctly configured with a valid SSL certificate. Make sure the certificate is correctly installed on your GitLab server and that it's accessible. Also, make sure that the gitlab_url setting in your OpenHands configuration is correct.

Debugging and Further Steps

If the above steps don’t work immediately, here's how to debug the issue:

Check the Certificate Details: Verify that the certificate details (domain, issuer, etc.) match your GitLab instance. Ensure the certificate is valid for the domain you're trying to connect to. In your web browser, navigate to your GitLab instance and check the certificate details.
Inspect Container Logs: Check the OpenHands container logs for more detailed error messages. Use docker logs <container_name> to view the logs and identify any additional clues.
Test with openssl: Use openssl s_client -connect your.gitlab.com:443 to test the SSL connection from the command line inside the container. This helps diagnose certificate issues. If the openssl command inside the container also fails to connect, there's likely an issue with the certificate itself or the network.

Conclusion

Getting OpenHands to work with a self-hosted GitLab instance can be a bit of a challenge, but by understanding the CERTIFICATE_VERIFY_FAILED error and following these steps, you should be able to resolve the issue. Remember, the best approach is to trust the certificate, and never bypass verification unless absolutely necessary. Good luck, and happy coding, folks! If you are still facing any problems, check out the OpenHands documentation and community forums. They might have additional information and solutions. The CERTIFICATE_VERIFY_FAILED error is a common hurdle when integrating applications with self-hosted GitLab instances. By understanding the root cause and implementing the appropriate solutions, you can ensure smooth and secure communication between OpenHands and your GitLab server.