[TFE] Issue uploading state files larger than 512MB – HashiCorp Help Center

Introduction

Terraform Enterprise has a default configuration that limits the maximum size of a state file to 512MB. When a state file exceeds this limit, you may encounter errors during state-related operations.

Problem

After a successful apply in a Terraform Enterprise workspace, a state file larger than 512MB is not visible in the States tab. Manually pushing a state file larger than 512MB using the Terraform CLI also fails with connection errors.

Example of a failed terraform state push command.

$ terraform state push ~/sv-xAY4npZExGMS0J3x.tfstate
Releasing state lock. This may take a few moments...
There was an error connecting to the remote backend. Please do not exit
Terraform to prevent data loss! Trying to restore the connection...
Still trying to restore the connection... (3s elapsed)
Still trying to restore the connection... (6s elapsed)
Still trying to restore the connection... (9s elapsed)

The Terraform Enterprise archivist.log may show the following error, indicating the string exceeds the maximum allowed size.

{
  "@level": "error",
  "@message": "failed copying data to cache store",
  "@module": "archivist.server.http.stream-download",
  "@timestamp": "2025-02-05T11:00:15.318439Z",
  "cache-hit": false,
  "err": "ERR string exceeds maximum allowed size (proto-max-bulk-len)",
  "obj.compressed": true,
  "obj.encrypted": true,
  "obj.expire": 1738843213,
  "obj.key": "terraform/states/sv-xAY4npZExGMS0J3x/xxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "obj.mode": "r",
  "obj.stream": true,
  "opts.framing": "*/*",
  "opts.limit": 0,
  "opts.offset": 0,
  "req.amazon_trace_id": "-",
  "req.id": "-"
}

Prerequisites

An active installation of Terraform Enterprise.
A Terraform state file larger than 512MB.

Cause

The proto-max-bulk-len attribute in the Redis configuration defaults to 512MB. Terraform Enterprise uses Redis for caching, and if a state file is larger than this limit, it cannot be cached, causing the operation to fail.

Solutions

There are three potential solutions. The first solution is the recommended best practice.

Solution 1: Reduce the state file size

The preferred solution is to reduce the size of your Terraform state file. Large state files can impact performance and are often an indicator that a configuration manages too many resources. Consider refactoring your configuration by splitting resources across multiple, more focused workspaces.

Solution 2: Use the Terraform CLI for the apply

As a temporary measure, you can perform the apply locally using the Terraform CLI configured with an HCP Terraform or Terraform Enterprise backend. This approach bypasses the specific caching mechanism in the Terraform Enterprise UI that is affected by the Redis limit.

Solution 3: Adjust the Redis `proto-max-bulk-len` setting

You can increase the proto-max-bulk-len setting in Redis. The method depends on whether you are using an external or internal Redis instance with Terraform Enterprise.

For external Redis

Modify your redis.conf file to increase the limit. Refer to the official Redis configuration documentation for guidance.

## In the Redis protocol, bulk requests, that are, elements representing single
## strings, are normally limited to 512 mb. However you can change this limit
## here, but must be 1mb or greater

proto-max-bulk-len 1024mb

For internal Redis (Workaround)

For the internal Redis instance managed by Terraform Enterprise, you can adjust the proto-max-bulk-len value using the Redis CLI. Note that this change is temporary and will not persist if the Redis container restarts.

Access the Terraform Enterprise container by following the guide to Access the Terraform Enterprise CLI.

Retrieve your Redis password.

$ tfectl app config --unredacted | jq .redis.password

Connect to the Redis CLI using the password from the previous step.
```
$ redis-cli -a '<your-redis-password>'
```

Inside the Redis CLI, check the current value and set a new one. This example sets the limit to 1GB (1073741824 bytes).

127.0.0.1:6379> CONFIG GET proto-max-bulk-len
1) "proto-max-bulk-len"
2) "536870912"

127.0.0.1:6379> config set proto-max-bulk-len 1073741824
OK

127.0.0.1:6379> CONFIG GET proto-max-bulk-len
1) "proto-max-bulk-len"
2) "1073741824"

Outcome

After applying one of these solutions, you will be able to manage workspaces with state files larger than 512MB. Be aware that setting a very high proto-max-bulk-len value may have performance implications on your Redis instance.

Additional Information