How to fix read-only file system in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 30, 2025· 108 views

The "read-only file system" error occurs when Terraform cannot write to directories needed for state files, plugins, or temporary operations. This typically happens in containerized or restricted environments. Fix by ensuring writable directories are available and properly mounted.

Quick fix

Fixes read-only file system

# Check mount status
mount | grep " / "
# Look for "ro" flag - if you see it, filesystem is read-only

# Try to touch a test file in working directory
touch test-file.txt
rm test-file.txt
  1. Verify filesystem is writable
  2. Check disk space
  3. Verify working directory permissions
  4. For Docker containers, mount writable volumes
terraform — error
# Check mount status
mount | grep " / "
# Look for "ro" flag - if you see it, filesystem is read-only
# Try to touch a test file in working directory
touch test-file.txt
rm test-file.txt
read-only file system

What this error means

The "read-only file system" error indicates that Terraform is attempting to write to a directory or file on a filesystem that has been mounted or configured as read-only. Terraform needs write access to several locations: 1. The working directory (for .terraform/ plugins and lock files) 2. The state file directory (for terraform.tfstate and backups) 3. Temporary directories (for provider caching and operations) When any of these locations are read-only, Terraform operations fail at the point where a write is attempted.

Typical symptoms

  • Terraform init fails with read-only file system error
  • Cannot write to .terraform directory
  • State file operations fail
  • Provider plugin installation fails
  • Error occurs in Docker containers or restricted environments
  • Works on local machine but fails in CI/CD or cloud runners
  • Terraform lock file cannot be created

Common causes

  1. Working directory or root filesystem mounted as read-only
  2. Insufficient permissions on working directory
  3. Container filesystem configured as immutable/read-only
  4. Volume mount options preventing writes
  5. Disk is full and kernel remounted filesystem as read-only
  6. Temporary directories (/tmp) not writable
  7. State file directory on read-only storage
  8. Security policy or SELinux restrictions

How to fix "read-only file system"

1Verify filesystem is writable

Check if the filesystem is mounted as read-only:

bash
# Check mount status
mount | grep " / "
# Look for "ro" flag - if you see it, filesystem is read-only

# Try to touch a test file in working directory
touch test-file.txt
rm test-file.txt

If you see "(ro)" in the mount output, the filesystem is read-only.

2Check disk space

A full disk can cause the kernel to remount as read-only:

bash
# Check available space
df -h

# Look for 100% usage - this is critical
df -i  # Check inode usage too

# Clean up if needed
rm -rf /path/to/large/files

Free up disk space and the filesystem may remount automatically as writable.

3Verify working directory permissions

Ensure you have write permissions:

bash
# Check current directory permissions
ls -ld .

# Check if you can write (should complete without error)
touch .test-write && rm .test-write

# If permission denied, check user/group
id
groups

# Fix permissions if needed
chmod u+w .

The working directory must be writable by the user running Terraform.

4For Docker containers, mount writable volumes

Ensure the working directory is on a writable volume:

bash
# Run with writable volume
docker run -v /path/to/writable:/work \
  -w /work \
  hashicorp/terraform:latest init

# Or in docker-compose.yml
services:
  terraform:
    image: hashicorp/terraform:latest
    volumes:
      - ./terraform:/work
      - terraform-cache:/root/.terraform.d
    working_dir: /work

volumes:
  terraform-cache:

Avoid mounting directories as read-only (no :ro flag).

5Set TF_DATA_DIR for custom state/plugin location

If the default location is read-only, redirect to a writable location:

bash
# Set to writable directory
export TF_DATA_DIR=/tmp/.terraform

# Or in environment during apply
TF_DATA_DIR=/writable/path terraform init
TF_DATA_DIR=/writable/path terraform apply

This moves plugin cache and working files to a writable location.

6Remount filesystem as writable (if you have root access)

If the filesystem was remounted read-only due to errors:

bash
# Check current mounts
mount | grep " / "

# Remount as writable (requires sudo)
sudo mount -o remount,rw /

# Or for specific partition
sudo mount -o remount,rw /var

This is a temporary fix. Investigate why it was marked read-only (disk errors, full disk, etc.).

7Use remote state backend to bypass local write issues

Store state remotely instead of locally:

hcl
# terraform.tf
terraform {
  cloud {
    organization = "my-org"

    workspaces {
      name = "my-workspace"
    }
  }
}

# Or with S3
terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "us-east-1"
    dynamodb_table = "terraform-locks"
  }
}

Remote backends bypass local filesystem write requirements for state.

Advanced notes

In Kubernetes or Fargate environments, ensure persistent volumes are mounted at the working directory. The /tmp directory is commonly used for plugin caching - verify it's writable or set TF_PLUGIN_CACHE_DIR to an alternative. Some container security profiles (AppArmor, SELinux) can prevent writes - check logs with dmesg or journalctl for denials. In CI/CD systems like GitHub Actions or GitLab CI, the runner's filesystem is usually writable by default, but custom runners may have restrictions. For immutable infrastructure patterns, consider Terraform Cloud for state management and run operations to eliminate local filesystem requirements entirely.

Frequently asked questions

What does "read-only file system" mean?
The "read-only file system" error indicates that Terraform is attempting to write to a directory or file on a filesystem that has been mounted or configured as read-only. Terraform needs write access to several locations: 1. terraform/ plugins and lock files) 2.
How do I fix "read-only file system"?
The "read-only file system" error occurs when Terraform cannot write to directories needed for state files, plugins, or temporary operations. This typically happens in containerized or restricted environments. Fix by ensuring writable directories are available and properly mounted.
What causes "read-only file system"?
Working directory or root filesystem mounted as read-only Insufficient permissions on working directory Container filesystem configured as immutable/read-only
Is the "read-only file system" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading