What causes "Error starting script: %v" in hashicorp/terraform?

Ensure scripts start with a valid shebang (#!/bin/sh) and are uploaded with execute permission.

Error starting script: %v

Error message

Error starting script: %v

What it means

Returned by runScripts at resource_provisioner.go:279 when comm.Start(cmd) fails to begin executing the previously uploaded script at comm.ScriptPath(). The script bytes are already on the host; this is a failure to launch the process.

Source

Thrown at internal/builtin/provisioners/remote-exec/resource_provisioner.go:279

		defer outW.Close()
		defer errW.Close()

		go copyUIOutput(o, outR)
		go copyUIOutput(o, errR)

		remotePath := comm.ScriptPath()

		if err := comm.UploadScript(remotePath, script); err != nil {
			return fmt.Errorf("Failed to upload script: %v", err)
		}

		cmd = &remote.Cmd{
			Command: remotePath,
			Stdout:  outW,
			Stderr:  errW,
		}
		if err := comm.Start(cmd); err != nil {
			return fmt.Errorf("Error starting script: %v", err)
		}

		if err := cmd.Wait(); err != nil {
			return err
		}

		// Upload a blank follow up file in the same path to prevent residual
		// script contents from remaining on remote machine
		empty := bytes.NewReader([]byte(""))
		if err := comm.Upload(remotePath, empty); err != nil {
			// This feature is best-effort.
			log.Printf("[WARN] Failed to upload empty follow up script: %v", err)
		}
	}

	return nil
}

View on GitHub (pinned to c9def3e214)

Solutions

Ensure scripts start with a valid shebang (#!/bin/sh) and are uploaded with execute permission.
Confirm the interpreter (sh/bash/powershell) exists on the remote image.
Avoid spaces in the script path; quote if necessary.
Verify the instance is still running at apply time (not terminated by a parallel destroy).

Example fix

// before: script has no shebang / not executable
provisioner "remote-exec" { scripts = ["do-stuff.sh"] } // Error starting script

// after: use inline with shebang-equivalent or chmod first
provisioner "remote-exec" {
  inline = [
    "chmod +x /tmp/run.sh",
    "/tmp/run.sh",
  ]
}

Defensive patterns

Strategy: validation

Validate before calling

// Ensure scripts have a shebang and executable bit before upload.
func validateScript(path string) error {
    b := make([]byte, 2)
    f, _ := os.Open(path); defer f.Close()
    if _, err := f.Read(b); err != nil || string(b) != "#!" {
        return errors.New("script missing shebang")
    }
    return nil
}

Prevention

Start every remote-exec script with a shebang (#!/bin/sh).
chmod +x scripts and avoid spaces in remote paths.
Confirm the interpreter exists on the AMI/image used.

When it happens

Trigger: After UploadScript succeeds, the communicator (SSH/WinRM) fails to start the command bound to remotePath.

Common situations: Script lacks the executable bit or a shebang; the remote shell/interpreter is missing; path with spaces or quoting issues; resource (the instance) terminated between upload and start; WinRM command-shell restrictions.

Related errors

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/bf30f9b459b0a26a. Report an issue: GitHub.