# Troubleshooting

Fixes for common Terraform problems in Buddy: missing plan file, Apply on the wrong state, artifact not found, stale plans, image tags, and state locks.

## Apply can't find the plan file

Apply uses the plan file from a Plan action **in the same run**. It fails when:

- the pipeline has no Plan action before Apply, or Plan was skipped by a trigger condition,
- Apply runs in a different run than Plan, for example in another pipeline.

Put Plan and Apply in one pipeline. If one run has several Plan actions, set `plan_file_path` in each Apply. See [The plan file](/docs/terraform/plan-and-apply.md#the-plan-file).

## Apply changes a different state than the plan

Plan and Apply have different `tf_workspace` or `backend` settings. Use exactly the same values in both. Check `BUDDY_ACTION_TF_PLAN_WORKSPACE` and `BUDDY_ACTION_TF_APPLY_WORKSPACE` in the run.

## Apply fails after changing the working directory or tool

Apply doesn't run `init`. It reuses the `.terraform` directory that Plan created in its `working_directory`. Use the same `working_directory`, `tool`, and `version` in both actions.

## Saved plan is stale

The state changed between Plan and Apply, for example because another run applied in the meantime. Terraform refuses to apply an outdated plan. Run the pipeline again to create a new plan. To avoid this, don't run several pipelines that apply to the same state at once. See [Concurrency](/docs/pipelines/concurrency-and-parallelism.md).

## Artifact not found

With the [artifact backend](/docs/terraform/state.md#artifact), the action fails with *not found* when the artifact or its version doesn't exist. Buddy doesn't create them. Create the artifact (type **Bucket**) and its version, then run again. If both exist, check that the pipeline has **read-write** access to the artifact.

## Pipeline is not allowed to publish artifact

With the [artifact backend](/docs/terraform/state.md#artifact), the action fails with *Pipeline is not allowed to publish artifact* when the pipeline has only read access to the artifact, or none. Every pipeline that works on the state needs **read-write** access, including a separate drift check pipeline. Give it access in the **Permissions** tab of the artifact, then run again.

## Backend configuration changed

With the artifact backend, your code must not declare its own `backend` block. Buddy adds `buddy_backend.tf` with an HTTP backend, and two backends in one configuration fail at `init`. Remove the `backend` block from your code, or switch to the `CUSTOM` backend.

## Workspaces not supported

The artifact backend supports only the `default` workspace. Remove `tf_workspace`, or keep each environment in its own artifact version. See [Workspaces and environments](/docs/terraform/workspaces-and-environments.md).

## Image pull fails

`version` is used as the image tag, and it's only checked when the image is pulled at run time, not when you save the action. Check that the tag exists in [`ghcr.io/opentofu/opentofu`](https://github.com/opentofu/opentofu/pkgs/container/opentofu) or [`hashicorp/terraform`](https://hub.docker.com/r/hashicorp/terraform/tags). For a custom image, check the image name, tag, and registry credentials.

## Unsupported Terraform Core version

Your code has a `required_version` constraint that the `version` in the action doesn't satisfy:

```hcl
terraform {
  required_version = ">= 1.6"
}
```

Terraform open-source in the `TERRAFORM` tool goes up to 1.5.7. Pick a `version` that matches the constraint, switch `tool` to `OPENTOFU`, or relax the constraint in your code.

## The custom binary isn't found

With the `CUSTOM` tool, `custom_binary_path` must be an absolute path to an executable inside the image, for example `/usr/local/bin/tofu`. See [Custom](/docs/terraform/versions.md#custom).

## Error acquiring the state lock

Another action holds the lock on the same state, or a previous run was terminated before it released the lock.

- Add `-lock-timeout=5m` to `additional_args` to wait for the lock instead of failing.
- If no run is using the state, remove the stale lock with `terraform force-unlock <LOCK_ID>` in the [Terraform CLI action](/docs/terraform/terraform-cli.md).

## No resource diff

The diff is built from the JSON plan. If the tool failed before writing it - for example during `init` or because of a syntax error - there is no diff. Check the action logs for the error.

With the `CUSTOM` tool, the binary must write the plan as JSON with `show -json`, in the same format as Terraform and OpenTofu.

## The diff hides values

Values marked `sensitive` appear as `(sensitive value)`. In Plan, values that are unknown until the apply appear as `(known after apply)`. Apply fills them in with the real values.


---
Original source: https://buddy.works/docs/terraform/troubleshooting