Terraform Enterprise Flexible Deployment Option (FDO) failing disk check – HashiCorp Help Center

Problem

During a Terraform Enterprise Flexible Deployment Option (FDO) installation, the process fails due to a disk check error.

Executing the docker logs <container ID> command reveals the following error in the container logs.

[ERROR] terraform-enterprise: check failed: name=disk duration=\"355.554µs\" err=\"open /var/lib/terraform-enterprise/check disk: read-only file system\"","component":"terraform-enterprise"}

Prerequisites

Terraform Enterprise Flexible Deployment Option (FDO)
Docker
Mounted Disk installation method

Cause

Terraform Enterprise performs a mandatory read/write disk check on its primary data directory, /var/lib/terraform-enterprise, during startup. This check fails if the compose.yaml file does not define a volume mount for this specific target directory.

The issue occurs because the configuration only mounts subdirectories (/var/lib/terraform-enterprise/postgres and /var/lib/terraform-enterprise/archivist) instead of the parent directory. Terraform Enterprise expects the entire /var/lib/terraform-enterprise path to be writable, not just the sub-paths for its internal services.

In the following example compose.yaml excerpt, the volume configuration is missing a mount for the /var/lib/terraform-enterprise target, which causes the disk check to fail.

volumes:
  - type: bind
    source: /opt/tfe/postgres/pgdata
    target: /var/lib/terraform-enterprise/postgres
  - type: bind
    source: /opt/tfe/aux/archivist
    target: /var/lib/terraform-enterprise/archivist

Solutions

Solution 1: Define a Volume Bind for the Root TFE Directory

To resolve this issue, update your compose.yaml file to include a volume bind configuration that maps a host directory to the /var/lib/terraform-enterprise target path.

volumes:
  - type: bind
    source: <mounted_disk_path_on_host>
    target: /var/lib/terraform-enterprise

Outcome

After applying the corrected volume configuration, the Terraform Enterprise installation will pass the disk check and proceed successfully.

Additional Information

For more details on file permissions, refer to this guide on Linux folder permissions.
For a complete configuration example, see the Terraform Enterprise Flexible Deployment Option - Mount Disk install compose.yaml example in the official documentation.