oraios/serena · error · RuntimeError

Terraform executable not found, please ensure Terraform is i

Error message

Terraform executable not found, please ensure Terraform is installed.See https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli for instructions.

What it means

TerraformLS._ensure_tf_command_available verifies that a `terraform` binary is discoverable on PATH or via TERRAFORM_CLI_PATH before starting the server. If no executable is found anywhere it checks, it raises RuntimeError with a link to HashiCorp's install guide, because terraform-ls requires the Terraform CLI to operate.

Source

Thrown at src/solidlsp/language_servers/terraform_ls.py:115

            return

        # TODO: is this needed?
        # 2. Fallback to TERRAFORM_CLI_PATH (set by hashicorp/setup-terraform action)
        if not terraform_cmd:
            terraform_cli_path = os.environ.get("TERRAFORM_CLI_PATH")
            if terraform_cli_path:
                log.debug(f"Trying TERRAFORM_CLI_PATH: {terraform_cli_path}")
                # TODO: use binary name from runtime dependencies if we keep this code
                if os.name == "nt":
                    terraform_binary = os.path.join(terraform_cli_path, "terraform.exe")
                else:
                    terraform_binary = os.path.join(terraform_cli_path, "terraform")
                if os.path.exists(terraform_binary):
                    terraform_cmd = terraform_binary
                    log.debug(f"Found terraform via TERRAFORM_CLI_PATH: {terraform_cmd}")
                    return

        raise RuntimeError(
            "Terraform executable not found, please ensure Terraform is installed."
            "See https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli for instructions."
        )

    @classmethod
    def _setup_runtime_dependencies(cls, solidlsp_settings: SolidLSPSettings) -> str:
        """
        Setup runtime dependencies for terraform-ls.
        Downloads and installs terraform-ls if not already present.
        """
        cls._ensure_tf_command_available()
        terraform_settings = solidlsp_settings.get_ls_specific_settings(LanguageServerId.TERRAFORM)
        terraform_ls_version = terraform_settings.get("terraform_ls_version", DEFAULT_TERRAFORM_LS_VERSION)
        platform_id = PlatformUtils.get_platform_id()
        deps = RuntimeDependencyCollection(
            [
                RuntimeDependency(
                    id="TerraformLS",

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install Terraform following https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli and ensure `terraform -version` works in the same shell.
Set TERRAFORM_CLI_PATH to the directory containing the `terraform` binary (e.g. /usr/local/bin), not the binary path itself.
In CI/Docker, install Terraform in the image or via a setup step (e.g. hashicorp/setup-terraform action) before running the language server.

Example fix

// before
TERRAFORM_CLI_PATH=/usr/local/bin/terraform  # points at the binary, not the dir
// after
export TERRAFORM_CLI_PATH=/usr/local/bin  # dir containing `terraform`
# or simply: export PATH="/usr/local/bin:$PATH"

Defensive patterns

Strategy: validation

Validate before calling

import shutil, os
assert shutil.which("terraform") or (
    os.environ.get("TERRAFORM_CLI_PATH")
    and os.path.isfile(os.path.join(os.environ["TERRAFORM_CLI_PATH"], "terraform"))
), "terraform must be on PATH or TERRAFORM_CLI_PATH must point to its directory"

Type guard

def terraform_available() -> bool:
    if shutil.which("terraform"):
        return True
    p = os.environ.get("TERRAFORM_CLI_PATH")
    return bool(p) and os.path.isfile(os.path.join(p, "terraform"))

Try / catch

try:
    server = SolidLanguageServer.create("terraform")
except RuntimeError as e:
    if "Terraform executable not found" in str(e):
        raise SystemExit("Install terraform: https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli") from e
    raise

Prevention

Install Terraform in dev images and CI containers as a setup step.
Set TERRAFORM_CLI_PATH to the directory containing the binary, not the binary itself.
Verify with `terraform -version` in the same environment that launches the language server.

When it happens

Trigger: Calling SolidLanguageServer.create("terraform") (or starting the server) via _setup_runtime_dependencies when `terraform` is not on PATH and TERRAFORM_CLI_PATH is unset or does not point to a directory containing a `terraform` binary.

Common situations: Fresh machines/CI containers without Terraform installed; TERRAFORM_CLI_PATH pointing to the binary instead of its containing directory; `terraform` installed only in a user dir not on PATH (e.g. via tfenv not linked); minimal Docker images.

Related errors

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/8c5de380fbba8d0c. Report an issue: GitHub.