The built-in vcl_recv subroutine is executed when a client request is received by Fastly or as a result of a restart.

Typically, the recv state is used for tasks such as:

The default return path from vcl_recv is lookup, which will trigger the vcl_hash subroutine, perform a cache key calculation and lookup the resulting address in the cache, ultimately triggering the vcl_hit, vcl_miss or vcl_pass subroutines as appropriate. It's also possible to return(pass), which will still perform a cache key calculation, but will always transition from vcl_hash to vcl_pass.

Changes made to the req object in vcl_recv will affect the calculation of the cache key, if the changed properties are included in obj.hash by vcl_hash.

The exception statements restart and error may both be used in recv.

State transitions

  • Inbound request
  • restart
  • return(lookup)hash
  • return(pass)hash
  • errorhash
  • restartrecv

To see this subroutine in the context of the full VCL flow, see using VCL.


The solution recipe URL path based routing for microservices is a good example of the vcl_recv subroutine in use:

Tokens available in this subroutine

The following limited-scope VCL functions and variables are available for use in this subroutine (those in bold are available only in this subroutine):

User contributed notes

We welcome comments that add use cases, ideas, tips, and caveats. All comments will be moderated before publication. To post support questions, visit our support center and we'll find you the help you need.