Terraform Cloud Working Directory Behavior Across Workspace Types

Summary

When switching a workspace in Terraform Cloud from a VCS-driven connection to an API-driven connection, users may encounter unexpected behavior related to working directories. This can result in Terraform failing to detect configuration files and returning errors during plan or apply stages.

This article explains why this happens and what causes the issue.

Symptoms

After switching a workspace from a VCS-driven workflow to an API-driven one (e.g., via GitHub Actions or CI/CD), you may see an error like the following:

Error: No Terraform configuration files found in working directory

Terraform requires configuration files to plan changes...
...
failed checking for terraform files: lstat /home/tfc-agent/.../infra: no such file or directory

This typically happens even though configuration files exist in the intended directory structure and were previously working under the VCS workflow.

Cause

When a Terraform Cloud workspace is configured via a VCS connection, you can specify a Terraform Working Directory (e.g., ./infra/dave). This setting tells Terraform where to look for .tf files relative to the repository root.

When switching to an API-driven workflow (e.g., via the upload-configuration GitHub Action), two directory paths are now in play:

1. Terraform Working Directory (from the workspace UI or settings)

2. Config Directory (set in the upload-configuration GitHub Action workflow YAML)

How They Interact

• The upload-configuration tool uploads files starting from the Config Directory, which is relative to the Terraform Working Directory set in the workspace.

• If both are set (e.g., Working Directory = ./infra/dave and Config Directory = ./nested_infra/dave), then Terraform tries to upload from:

./infra/dave/nested_infra/dave

If this nested path doesn’t exist in your repo, no .tf files are uploaded — which causes Terraform to fail during the plan phase.

Conclusion

This behavior is expected based on how Terraform Cloud handles configuration uploads and working directories. The key is understanding how the workspace settings interact with CI/CD workflows.