Restore API error "413 Request Entity Too Large"

Problem

When attempting to restore a Terraform Enterprise backup to a new instance, the restore API request fails with the following error message.

413 Request Entity Too Large

Cause

This error occurs when the restore request is sent to the Terraform Enterprise server's IP address instead of its configured Fully Qualified Domain Name (FQDN).

The Nginx proxy within Terraform Enterprise uses different server blocks based on the request's Host header. A request to the IP address may be routed to a default server block with a low client_max_body_size limit, causing the rejection of the large backup file.

An inspection of the Nginx logs on the Terraform Enterprise instance may show an error similar to the following.

[error] 9#9: *5600 client intended to send too large body: 52735116065 bytes, client: 10.5.110.36, server: , request: "POST /_backup/api/v1/restore HTTP/1.1", host: "TFE_ip.eu-west-1.compute.internal"

Solution

To resolve this issue, you must send the restore request to the FQDN of the Terraform Enterprise instance as configured in its application settings. This ensures Nginx uses the correct server block that is configured to accept large file uploads.

Procedure

1. On the machine where you are running the restore command, ensure the Terraform Enterprise FQDN resolves to the correct private IP address. If necessary, add an entry to the /etc/hosts file.

   ## Add the following line to /etc/hosts, replacing the values with your own
   $ echo "10.0.1.10 tfe.example.com" | sudo tee -a /etc/hosts

2. Execute the restore command using the FQDN in the URL. This example uses curl to submit the request.

   $ curl --header "Authorization: Bearer YOUR_TOKEN" \
     --request POST \
     --form config=@payload.json \
     --form snapshot=@backup.blob \
     https://tfe.example.com/_backup/api/v1/restore

   A successful request will return a message indicating the snapshot was applied.

   snapshot applied successfully

Additional Information

For more details on the backup and restore process, please refer to the official Terraform Enterprise Backup and Restore API documentation.