Understanding the 308 Status Code

Oct 13, 2025 by wbrum.org 42 views

Introduction

When trying to put Mercury into production on a VPS server (Ubuntu 22.04 and Nginx) using Docker, you may encounter a 308 status code: Number of redirects hit maximum amount. This issue can be frustrating, especially when you're not sure where to start looking for the solution. In this article, we'll explore the possible causes of this error and provide a step-by-step guide to resolve it.

Understanding the 308 Status Code

The 308 status code is a permanent redirect, which means that the client should automatically redirect to the new location. However, in this case, the number of redirects has hit the maximum amount, indicating that there's an issue with the redirect chain.

Analyzing the Nginx Configuration

Let's take a closer look at the Nginx configuration provided:

server {
    server_name mercure.mydomain.com;

    location / {
        proxy_pass http://localhost:3001;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Enable fast reply in SSE
        proxy_buffering off;

        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_read_timeout 24h;
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/mercure.mydomain.com/fullchain.pem; >
    ssl_certificate_key /etc/letsencrypt/live/mercure.mydomain.com/privkey.pem>
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = mercure.mydomain.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;
    server_name mercure.mydomain.com;
    return 404; # managed by Certbot

}

The first server block listens on port 443 (HTTPS) and proxies requests to http://localhost:3001. The second server block listens on port 80 (HTTP) and returns a 404 error if the host is mercure.mydomain.com.

Analyzing the Docker Configuration

Let's take a closer look at the Docker configuration provided:

services:
  mercure:
    container_name: "mercure"
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      
      - MERCURE_PUBLISHER_JWT_KEY="The key"
      - MERCURE_SUBSCRIBER_JWT_KEY="The key"
      
      - MERCURE_CORS_ALLOWED_ORIGINS=*
      - MERCURE_PUBLISH_ALLOWED_ORIGINS=*
      
      - MERCURE_EXTRA_DIRECTIVES=anonymous
      - MERCURE_UI=1
    ports:
      - "3001:80"
    volumes:
      - mercure_data:/data

volumes:
  mercure_data: {}

The Docker configuration uses the dunglas/mercure image and exposes port 3001. The MERCURE_UI=1 environment variable enables the Mercury UI.

Possible Causes of the 308 Status Code

Based on the provided configurations, there are a few possible causes of the 308 status code:

Redirect Loop: The Nginx configuration has a redirect from HTTP to HTTPS, which may cause a redirect loop if the client is not properly configured to follow redirects.
Proxy Pass: The Nginx configuration uses a proxy pass to forward requests to http://localhost:3001. If the proxy pass is not properly configured, it may cause a redirect loop.
Docker Configuration: The Docker configuration exposes port 3001, but the Nginx configuration is listening on port 443 (HTTPS). This may cause a redirect loop if the client is not properly configured to follow redirects.

Resolving the 308 Status Code

To resolve the 308 status code, you can try the following steps:

Disable Redirects: Disable redirects in the Nginx configuration by commenting out the return 301 statement in the second server block.
Configure Proxy Pass: Configure the proxy pass in the Nginx configuration to properly forward requests to http://localhost:3001.
Update Docker Configuration: Update the Docker configuration to expose port 443 (HTTPS) instead of port 3001.
Verify Configuration: Verify that the Nginx and Docker configurations are properly configured and that there are no redirect loops.

Conclusion

The 308 status code: Number of redirects hit maximum amount can be caused by a redirect loop in the Nginx configuration or a misconfigured proxy pass. By disabling redirects, configuring the proxy pass, and updating the Docker configuration, you can resolve this issue. Remember to verify your configuration to ensure that there are no redirect loops.

Additional Tips

Make sure to test your configuration thoroughly to ensure that there are no redirect loops.
Consider using a load balancer or a reverse proxy to handle redirects and proxy passes.
Keep your Nginx and Docker configurations up to date to ensure that you have the latest features and security patches.

References

Nginx Documentation
Docker Documentation
Mercure Documentation
308 Status Code: Number of Redirects Hit Maximum Amount with Nginx and Docker on a Ubuntu VPS - Q&A ===========================================================================================

Introduction

In our previous article, we explored the possible causes of the 308 status code: Number of redirects hit maximum amount with Nginx and Docker on a Ubuntu VPS. We also provided a step-by-step guide to resolve this issue. In this article, we'll answer some frequently asked questions (FAQs) related to this topic.

Q: What is the 308 status code?

A: The 308 status code is a permanent redirect, which means that the client should automatically redirect to the new location. However, in this case, the number of redirects has hit the maximum amount, indicating that there's an issue with the redirect chain.

Q: What are the possible causes of the 308 status code?

A: The possible causes of the 308 status code include:

Redirect Loop: The Nginx configuration has a redirect from HTTP to HTTPS, which may cause a redirect loop if the client is not properly configured to follow redirects.
Proxy Pass: The Nginx configuration uses a proxy pass to forward requests to http://localhost:3001. If the proxy pass is not properly configured, it may cause a redirect loop.
Docker Configuration: The Docker configuration exposes port 3001, but the Nginx configuration is listening on port 443 (HTTPS). This may cause a redirect loop if the client is not properly configured to follow redirects.

Q: How can I resolve the 308 status code?

A: To resolve the 308 status code, you can try the following steps:

Disable Redirects: Disable redirects in the Nginx configuration by commenting out the return 301 statement in the second server block.
Configure Proxy Pass: Configure the proxy pass in the Nginx configuration to properly forward requests to http://localhost:3001.
Update Docker Configuration: Update the Docker configuration to expose port 443 (HTTPS) instead of port 3001.
Verify Configuration: Verify that the Nginx and Docker configurations are properly configured and that there are no redirect loops.

Q: What are some additional tips to prevent the 308 status code?

A: Here are some additional tips to prevent the 308 status code:

Test Configuration: Test your configuration thoroughly to ensure that there are no redirect loops.
Use a Load Balancer or Reverse Proxy: Consider using a load balancer or a reverse proxy to handle redirects and proxy passes.
Keep Configurations Up to Date: Keep your Nginx and Docker configurations up to date to ensure that you have the latest features and security patches.

Q: What are some common mistakes that can cause the 308 status code?

A: Here are some common mistakes that can cause the 308 status code:

Incorrect Proxy Pass Configuration: Incorrectly configuring the proxy pass can cause a redirect loop.
Incorrect Docker Configuration: Incorrectly configuring the Docker container can cause a redirect loop.
Incorrect Nginx Configuration: Incorrectly configuring the Nginx server can cause a redirect loop.

Q: How can I troubleshoot the 308 status code?

A: To troubleshoot the 308 status code, you can try the following steps:

Check Nginx Logs: Check the Nginx logs to see if there are any errors or warnings related to the redirect loop.
Check Docker Logs: Check the Docker logs to see if there are any errors or warnings related to the redirect loop.
Use a Debugging Tool: Use a debugging tool such as curl or wget to test the redirect loop and see if it's causing the 308 status code.

Conclusion

The 308 status code: Number of redirects hit maximum amount can be caused by a redirect loop in the Nginx configuration or a misconfigured proxy pass. By disabling redirects, configuring the proxy pass, and updating the Docker configuration, you can resolve this issue. Remember to test your configuration thoroughly and keep your Nginx and Docker configurations up to date to prevent this issue.