How to Customize Varnish 4 503 Error Page with HTML and Retry-After Header

When Varnish can't reach your backend server, it returns a 503 Service Unavailable error. In Varnish 4, you can customize this response using the vcl_synth subroutine in your VCL configuration.

Here's a complete VCL example to customize your 503 error page:

sub vcl_synth {
    if (resp.status == 503) {
        set resp.http.Content-Type = "text/html; charset=utf-8";
        set resp.http.Retry-After = "5";
        synthetic( {"<!DOCTYPE html>
<html>
  <head>
    <title>Service Temporarily Unavailable</title>
    <style>
      body { font-family: Arial, sans-serif; text-align: center; padding: 50px; }
      h1 { color: #d9534f; }
    </style>
  </head>
  <body>
    <h1>Service Temporarily Unavailable</h1>
    <p>We're performing maintenance. Please try again in a few minutes.</p>
    <p>Retry after: "} + resp.http.Retry-After + {" seconds</p>
  </body>
</html>
"} );
        return (deliver);
    }
}

For production environments, consider these enhancements:

sub vcl_synth {
    if (resp.status == 503) {
        set resp.http.Content-Type = "text/html; charset=utf-8";
        set resp.http.Retry-After = "10";
        set resp.http.Cache-Control = "no-cache, no-store, must-revalidate";
        
        synthetic( {"<!DOCTYPE html>
<html>
  <head>
    <title>Maintenance in Progress</title>
    <meta http-equiv=\"refresh\" content=\""} + resp.http.Retry-After + {"\">
    <style>
      /* Add your custom CSS here */
    </style>
  </head>
  <body>
    <div class=\"error-container\">
      <h1>We'll be back soon!</h1>
      <p>Our service is currently undergoing maintenance.</p>
      <p>Automatic refresh in "} + resp.http.Retry-After + {" seconds.</p>
      <button onclick=\"window.location.reload()\">Refresh Now</button>
    </div>
  </body>
</html>
"} );
        return (deliver);
    }
}

After adding this to your VCL file:

Reload your Varnish configuration: varnishadm vcl.load newconfig /etc/varnish/default.vcl
Activate it: varnishadm vcl.use newconfig
Test by temporarily taking your backend offline

Keep the error page lightweight (under 15KB)
Include your brand styling for consistency
Set appropriate Cache-Control headers
Provide clear instructions and expected downtime
Consider adding a status page link

When your backend server is unavailable, Varnish returns a 503 Service Unavailable response. By default, this shows a plain error page, but we can customize it using Varnish Configuration Language (VCL).

Here's the standard approach to modify the 503 error page in Varnish 4:

sub vcl_synth {
    if (resp.status == 503) {
        set resp.http.Content-Type = "text/html; charset=utf-8";
        set resp.http.Retry-After = "5";
        synthetic( {"<!DOCTYPE html>
<html>
  <head>
    <title>Service Temporarily Unavailable</title>
  </head>
  <body>
    <h1>Maintenance in Progress</h1>
    <p>We're currently performing maintenance. Please try again later.</p>
  </body>
</html>
"} );
        return (deliver);
    }
}

For more sophisticated implementations, consider these enhancements:

Adding CSS Styling

sub vcl_synth {
    if (resp.status == 503) {
        set resp.http.Content-Type = "text/html; charset=utf-8";
        synthetic( {"<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: Arial, sans-serif; text-align: center; padding: 50px; }
        .container { max-width: 600px; margin: 0 auto; }
        h1 { color: #e74c3c; }
        .logo { max-width: 200px; margin-bottom: 20px; }
    </style>
    <title>Service Unavailable</title>
</head>
<body>
    <div class="container">
        <img src="/logo.png" class="logo" alt="Company Logo">
        <h1>We'll Be Right Back</h1>
        <p>Our services are currently undergoing maintenance.</p>
        <p>Expected downtime: 30 minutes</p>
    </div>
</body>
</html>
"} );
        return (deliver);
    }
}

Dynamic Content Based on Error Cause

sub vcl_synth {
    if (resp.status == 503) {
        set resp.http.Content-Type = "text/html; charset=utf-8";
        
        declare local var.errorMsg STRING;
        if (req.backend.healthy) {
            set var.errorMsg = "High traffic load";
        } else {
            set var.errorMsg = "Backend server maintenance";
        }
        
        synthetic( {"<!DOCTYPE html>
<html>
<head>
    <title>503 Service Unavailable</title>
</head>
<body>
    <h1>Service Temporarily Unavailable</h1>
    <p>Reason: "} + var.errorMsg + {"</p>
    <p>Our team has been notified and is working on a solution.</p>
</body>
</html>
"} );
        return (deliver);
    }
}

When implementing custom error pages:

Always set the proper Content-Type header
Include a Retry-After header when appropriate
Keep the page lightweight (under 4KB for best performance)
Consider caching the error page if you expect frequent 503s

To test your custom 503 page:

varnishadm
vcl.load test503 /etc/varnish/default.vcl
vcl.use test503
backend.list
backend.set_health BE_NAME sick
# Now make requests to trigger 503