Terraform "Unreadable module directory" in CI

By Kaveh Alemi·Latchkey

Terraform tried to read a local module directory and could not. The path in a source = "./..." reference does not exist on the runner, or a symlink or the subdirectory after // cannot be resolved.

What this error means

terraform init or plan stops with "Error: Unreadable module directory" and "the directory ... could not be read" or "unable to evaluate directory symlink".

Error: Unreadable module directory

Unable to evaluate directory symlink: lstat modules/network: no such file or directory

Common causes

A local module path is missing on the runner

A source = "./modules/network" points to a directory that was not checked out, was gitignored, or lives outside the cloned path.

A submodule or sparse checkout omitted the directory

A shallow or sparse clone, or an uninitialized git submodule, left the referenced module directory absent.

How to fix it

Ensure the module directory is checked out

1. Confirm the local path in the source exists in the repo.
2. If the module is a git submodule, initialize submodules in the checkout step.
3. Avoid sparse/partial checkouts that drop module directories.

- uses: actions/checkout@v4
  with:
    submodules: recursive

Correct the local source path

Fix the relative source so it resolves from the config file location on the runner.

module "network" {
  source = "./modules/network"
}

How to prevent it

• Check out submodules recursively when modules live in them.
• Avoid sparse checkouts that exclude module directories.
• Keep local module paths relative to the config file.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation