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 to

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

if ( ~ “^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(, "^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.
  • 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