Terraform Stacks - Local paths have to be root level

[Gerruhtz]

Terraform Version

1.14.2

Terraform Configuration Files

component "virtual-machine" {
  source = "../../modules/vm"
  inputs = {
    servers      = 1
    env          = var.env
    hostname     = "test"
    vm_id        = 900
    cpu_cores    = 1
    memory       = 1024
    distribution = "ubuntu"
    release      = "noble"
    disk_size    = 20
  }
  providers = {
    proxmox           = provider.proxmox.this
    bitwarden-secrets = provider.bitwarden-secrets.this
  }
}

--- 

component "virtual-machine" {
  source = "./vm"
  inputs = {
    servers      = 1
    env          = var.env
    hostname     = "test"
    vm_id        = 900
    cpu_cores    = 1
    memory       = 1024
    distribution = "ubuntu"
    release      = "noble"
    disk_size    = 20
  }
  providers = {
    proxmox           = provider.proxmox.this
    bitwarden-secrets = provider.bitwarden-secrets.this
  }
}

Debug Output

2025-12-12T09:47:58.081+0100 [INFO]  Terraform version: 1.14.2
2025-12-12T09:47:58.081+0100 [DEBUG] using github.com/hashicorp/go-tfe v1.94.0
2025-12-12T09:47:58.081+0100 [DEBUG] using github.com/hashicorp/hcl/v2 v2.24.0
2025-12-12T09:47:58.081+0100 [DEBUG] using github.com/hashicorp/terraform-svchost v0.1.1
2025-12-12T09:47:58.081+0100 [DEBUG] using github.com/zclconf/go-cty v1.16.3
2025-12-12T09:47:58.081+0100 [INFO]  Go runtime version: go1.25.5
2025-12-12T09:47:58.081+0100 [INFO]  CLI args: []string{"terraform", "stacks", "init"}
2025-12-12T09:47:58.081+0100 [TRACE] Stdout is a terminal of width 237
2025-12-12T09:47:58.081+0100 [TRACE] Stderr is a terminal of width 237
2025-12-12T09:47:58.081+0100 [TRACE] Stdin is a terminal
2025-12-12T09:47:58.081+0100 [DEBUG] Attempting to open CLI config file: 
2025-12-12T09:47:58.081+0100 [DEBUG] File doesn't exist, but doesn't need to. Ignoring.
2025-12-12T09:47:58.081+0100 [DEBUG] ignoring non-existing provider search directory terraform.d/plugins
2025-12-12T09:47:58.081+0100 [DEBUG] ignoring non-existing provider search directory 
2025-12-12T09:47:58.081+0100 [DEBUG] ignoring non-existing provider search directory 
2025-12-12T09:47:58.081+0100 [DEBUG] ignoring non-existing provider search directory /Library/Application Support/io.terraform/plugins
2025-12-12T09:47:58.082+0100 [INFO]  CLI command args: []string{"stacks", "init"}
2025-12-12T09:47:58.082+0100 [TRACE] stacksplugin hostname not set, falling back to "app.terraform.io"
2025-12-12T09:47:58.082+0100 [DEBUG] Service discovery for app.terraform.io at https://app.terraform.io/.well-known/terraform.json
2025-12-12T09:47:58.478+0100 [TRACE] No stacksplugin cache path store at '.terraform/.stackspluginpath`, using default '/.terraform.d/stacksplugin'
2025-12-12T09:47:58.478+0100 [TRACE] stacksplugin cache directory found at "/.terraform.d/stacksplugin"
2025-12-12T09:47:58.479+0100 [TRACE] stacksplugin manifest cache found for host "app.terraform.io"
2025-12-12T09:47:58.479+0100 [DEBUG] performing request: method=GET url=https://app.terraform.io/stacksplugin.v1/manifest.json
2025-12-12T09:47:58.479+0100 [TRACE] HTTP client GET request to https://app.terraform.io/stacksplugin.v1/manifest.json
2025-12-12T09:47:58.867+0100 [TRACE] wrote stacksplugin manifest cache to "/.terraform.d/stacksplugin/app.terraform.io/manifest.json"
2025-12-12T09:47:58.867+0100 [TRACE] checking for stacksplugin archive for darwin_arm64. Supported architectures: [darwin_amd64 darwin_arm64 freebsd_386 freebsd_amd64 freebsd_amd linux_386 linux_amd64 linux_arm linux_arm64 netbsd_386 netbsd_amd64 netbsd_arm openbsd_386 openbsd_amd64 openbsd_arm solaris_amd64 windows_386 windows_amd64]
2025-12-12T09:47:58.868+0100 [TRACE] plugin "1.1.1" binary located at "/.terraform.d/stacksplugin/bin/darwin_arm64/tfstacks" (resolved from cache)
2025-12-12T09:47:58.868+0100 [DEBUG] created stacks logger: level=trace
2025-12-12T09:47:58.868+0100 [DEBUG] stacks: starting plugin: path=/.terraform.d/stacksplugin/bin/darwin_arm64/tfstacks args=["/.terraform.d/stacksplugin/bin/darwin_arm64/tfstacks"]
2025-12-12T09:47:58.873+0100 [DEBUG] stacks: plugin started: path=/.terraform.d/stacksplugin/bin/darwin_arm64/tfstacks pid=70598
2025-12-12T09:47:58.873+0100 [DEBUG] stacks: waiting for RPC address: plugin=/.terraform.d/stacksplugin/bin/darwin_arm64/tfstacks
2025-12-12T09:47:58.894+0100 [DEBUG] stacks: using plugin: version=1
2025-12-12T09:47:58.894+0100 [DEBUG] stacks.tfstacks: plugin address: address=/var/folders/6q/pkdcx5f97wj5hn4b5dms9j480000gn/T/plugin1075467194 network=unix timestamp="2025-12-12T09:47:58.894+0100"
2025-12-12T09:47:58.896+0100 [TRACE] stacks.stdio: waiting for stdio data
2025-12-12T09:47:58.898+0100 [TRACE] stacks.tfstacks: Plugin Execute with args [init]: timestamp="2025-12-12T09:47:58.898+0100"
2025-12-12T09:47:59.298+0100 [TRACE] stacks.tfstacks: sending command response to stderr: "\x1b[31m╷\x1b[0m\n\x1b[31m│\x1b[0m \x1b[31m\x1b[1mError: \x1b[0m\x1b[1mFailed to read configuration directory\x1b[0m\n\x1b[31m│\x1b[0m\n\x1b[31m│\x1b[0m Could not open configuration directory ../vm: readdir ../vm: invalid argument.\n\x1b[31m╵\x1b[0m": timestamp="2025-12-12T09:47:59.298+0100"
2025-12-12T09:47:59.298+0100 [TRACE] stacks.tfstacks: sending command response to stderr: "\n": timestamp="2025-12-12T09:47:59.298+0100"
2025-12-12T09:47:59.299+0100 [TRACE] stacks.tfstacks: sending command response to stdout: "\x1b[31m\x1b[1mFailure!\x1b[0m Could not initialize configuration.": timestamp="2025-12-12T09:47:59.298+0100"
2025-12-12T09:47:59.299+0100 [TRACE] stacks.tfstacks: sending command response to stdout: "\n": timestamp="2025-12-12T09:47:59.298+0100"
2025-12-12T09:47:59.299+0100 [TRACE] stacks.tfstacks: Plugin Execute sending ExitCode 1: timestamp="2025-12-12T09:47:59.298+0100"
2025-12-12T09:47:59.299+0100 [INFO]  stacks.tfstacks: Context cancelled, initiating graceful shutdown: timestamp="2025-12-12T09:47:59.298+0100"
╷
│ Error: Failed to read configuration directory
│
│ Could not open configuration directory ../vm: readdir ../vm: invalid argument.
╵
Failure! Could not initialize configuration.
2025-12-12T09:47:59.299+0100 [TRACE] received exit code: 1
2025-12-12T09:47:59.300+0100 [DEBUG] stacks.stdio: received EOF, stopping recv loop: err="rpc error: code = Unavailable desc = error reading from server: EOF"
2025-12-12T09:47:59.303+0100 [INFO]  stacks: plugin process exited: plugin=/.terraform.d/stacksplugin/bin/darwin_arm64/tfstacks id=70598
2025-12-12T09:47:59.303+0100 [DEBUG] stacks: plugin exited

Expected Behavior

Documentation says that the component block accepts the same module sources as traditional modules. https://developer.hashicorp.com/terraform/language/block/stack/tfcomponent/component#source

Actual Behavior

Running 'terraform stacks init' results in a crash where it can't read the module directory.

Steps to Reproduce

1. 'terraform stacks init'

Additional Context

Running on MacOS Tahoe 26.1

References

No response

Generative AI / LLM assisted development?

No response

[som14062005]

Hi, I’d like to help investigate this Stacks path bug on macOS. Could you confirm if the intention is to support relative paths outside the stack root?

[Gerruhtz]

Hi, thanks!

The intention is indeed to support relative paths beyond the stack root folder.

[som14062005]

Hi @Gerruhtz and Terraform team,

Thanks for confirming that the intention is to support relative paths outside the stack root.
My plan is to investigate the stacks plugin implementation on macOS, understand why paths outside the root fail, and propose a fix that allows valid relative paths while maintaining cross-platform compatibility.

Could you confirm if there are any specific guidelines or testing requirements for this change?

Thanks!

[Gerruhtz]

Hi @som14062005,

As far as I know the testing is straightforward. Trying to address a module somewhere above the stack root folder will result in a readdir error.

[som14062005]

Hi @Gerruhtz,

After looking into this more carefully, I realize this involves
Terraform Stacks internals and the plugin architecture which
is outside my current expertise. I apologize for jumping in
too quickly without fully understanding the scope.

I'll step back and let someone more familiar with the Terraform
codebase handle this. Good luck with the fix!

[crw]

Thanks for this report!

[nfagerlund]

So, as of today, HCP Terraform doesn't support specifying an inner working directory to use for the stack configuration; to the best of my understanding, the components config and the deployments config are always placed at the root of the stack repository.

(We have received several requests to enable specifying an inner working directory, like workspaces let you do. We would like to do this, but the work is not scheduled. There are likely to be some complexities around avoiding explosions of work due to large monorepos; it took a lot of iterations to make workspaces behave correctly in those conditions.)

Now, given that you can't actually run a stack config in an inner directory... can you tell me where exactly you're hoping ../../modules/vm would point to? Because from my read, that's an attempt to traverse outside the working directory that tfc-agent is executing the stack run in, which should always be an error and not allowed.

It sounds like maybe you're looking at this from a CLI-based point of view, where you're in a stack directory and trying to reference modules elsewhere on your own disk. But the only stuff that gets sent to HCP terraform to perform the stack run is your stack directory and its children; it doesn't get the rest of your disk, and tfc-agent has no idea what else is on your machine outside that directory.

(I mentioned complexities around making workspaces work correctly with monorepos — the question of how much outer directory to send to HCP Terraform was one big part of that complexity.)

---

All told, if my interpretations above are correct, then I think what you're ultimately asking for is the ability to run a stack config in an inner working directory nested inside a larger monorepo of some kind, which contains referenceable modules outside the stack config directory; furthermore, you might also want the terraform CLI to be able to detect that it's doing a stack operation inside a monorepo and correctly guess how many outer directories need to be wrapped up and sent to HCP Terraform to support a proper run.

Is that about right? If so, that's a feature enhancement that we've got our eye on, but which is not yet scheduled for work and which would have to compete with several other priorities.