How Does vcl_error Work?

Fastly uses errors to handle many different circumstances, e.g. creating different results for requests. Let’s look at what this process looks like if we want to redirect a request for www.example.com to example.com.

When the request comes in to vcl_recv, we can catch it using a conditional, something like:

if (req.http.host ~ “^www.”) {
    error 607 “Fastly www. Redirect”;
}

Then in vcl_error, we can make the changes that we want to our URL:

if (obj.status == 607) {
    set obj.status = 301;
    set obj.response = "Moved Permanently";
    set obj.http.Location = regsub(req.http.host, "^www\.","") req.url;
    synthetic {""};
    return (deliver);
}

Several important things to note here:

The error code generated in vcl_recv (i.e. 607 in this instance):
- Fastly strongly encourages using custom error codes in the 600’s or 700’s. This will avoid confusion with other error codes in the future.
- If a customer is using the UI to create the error, the number will be automatically generated for them.
- This is a status code used to look up what to do in the event of that error. If you want to send a different status code back to the browser, you can set obj.status in vcl_error or vcl_deliver and that will override the status code sent in with the error.
The response in vcl_recv (i.e. “Fastly www. Redirect” in this instance) isn’t required, but it should be.
- This status code can help out significantly in troubleshooting.
- If you want to make your vcl_error easier to read in the future, you can test for obj.response; e.g. if (obj.response == “Fastly www. Redirect”) { }.
You can create a synthetic response for errors as well.
- Using the UI.
- Or, you can type your HTML into the brackets at synthetic {""};. Find more information here
Errors always end with return (deliver);
- Depending on how you manipulated the request in your error, you may need to make some accommodations in vcl_deliver as well.
- If you don’t run a return, it falls through to master vcl. Things can go weird if that happens.

If you have any questions, support would love to troubleshoot with you. Email us at support@fastly.com.

Comments