1. Home
  2. Reference documentation
  3. VCL reference
  4. Subroutines

vcl_miss

The built-in vcl_miss subroutine is executed when a requested object is not found in the cache by the lookup operation.

The subroutines vcl_pass and vcl_miss are very similar in nature. They both run immediately prior to a backend fetch, usually on a fetch node. In preparation for making a request to the backend, a copy of the client request is created, and is available as bereq. This backend request object is writable, and any changes made to it do not affect the state of the client request, nor the cache address in which the response may be stored. This is therefore a good opportunity to remove any headers that you do not wish to send to the backend or to add authentication data required by the backend.

Key use cases:

  • Preparing request headers for a specific origin/backend.
  • Adding authentication requirements when the origin is a private bucket at AWS S3, GCS or similar.
  • Unsetting request headers that are being used internally in VCL and are not required at origin.

The vcl_miss subroutine should return(fetch) to start the backend fetch. It is also possible to return(pass), which will transfer control to the vcl_pass subroutine and ultimately still make a backend fetch, but the resulting response will not qualify for caching. error may be used in vcl_miss, but it is not possible to restart the request from here.

Typically vcl_miss is executed on a fetch node as a result of clustering.

Using a 'prefetch' custom subroutine

Since it is common for vcl_miss and vcl_pass to perform broadly the same tasks, it is often useful to create a custom subroutine and invoke it from both places:

sub miss_pass {
  # Common logic goes here
}
sub vcl_pass {
#FASTLY pass
  call miss_pass;
}
sub vcl_miss {
#FASTLY miss
  call miss_pass;
}

State transitions

  • hashreturn(hash) ⮕
vcl_miss

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

Example

The code example AWS S3 bucket origin (private) is a good example of the vcl_miss 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, those available in *all* subroutines are not listed):

Fastly
© Fastly 2024