hashicorp/terraform · error

unlock_address must be HTTP or HTTPS

Error message

unlock_address must be HTTP or HTTPS

What it means

unlock_address parsed successfully but its scheme is neither 'http' nor 'https'. Same scheme gate as address/lock_address is enforced for unlock_address.

Solutions

1. Set unlock_address to an http:// or https:// URL.
2. Keep the scheme consistent with lock_address and address.
3. Omit unlock_address to disable HTTP-level unlocking entirely.

Example fix

// before
unlock_address = "file:///var/lock/unlock"
// after
unlock_address = "https://state.example.com/unlock"

# Pre-flight: assert unlock_address scheme
if [ -n "$TF_HTTP_UNLOCK_ADDRESS" ]; then
  case "$TF_HTTP_UNLOCK_ADDRESS" in
    http://*|https://*) echo ok ;;
    *) echo "ERROR: unlock_address must be http(s): $TF_HTTP_UNLOCK_ADDRESS"; exit 1 ;;
  esac
fi

When it happens

Trigger: unlock_address set to a non-HTTP scheme such as 'ftp://', 'file://', or a scheme-less relative URL that url.Parse accepted with an empty/unexpected scheme.

Common situations: unlock_address copied from another backend URI; wrong-scheme value templated from a variable.

Related errors

• address must be HTTP or HTTPS
• failed to parse unlock_address URL
• lock_address must be HTTP or HTTPS
• failed to parse lock_address URL
• cannot load client certificate

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/556a5c3f26dd9950. Report an issue: GitHub.

Appendix: source

Thrown at internal/backend/remote-state/http/backend.go:178

		}
	}
	lockMethod := backendbase.GetAttrEnvDefaultFallback(
		configVal, "lock_method",
		"TF_HTTP_LOCK_METHOD", cty.StringVal("LOCK"),
	).AsString()

	var unlockURL *url.URL
	if v := backendbase.GetAttrEnvDefault(configVal, "unlock_address", "TF_HTTP_UNLOCK_ADDRESS"); !v.IsNull() {
		var err error
		unlockURL, err = url.Parse(v.AsString())
		if err != nil {
			return backendbase.ErrorAsDiagnostics(
				fmt.Errorf("failed to parse unlock_address URL: %s", err),
			)
		}
		if unlockURL.Scheme != "http" && unlockURL.Scheme != "https" {
			return backendbase.ErrorAsDiagnostics(
				fmt.Errorf("unlock_address must be HTTP or HTTPS"),
			)
		}
	}
	unlockMethod := backendbase.GetAttrEnvDefaultFallback(
		configVal, "unlock_method",
		"TF_HTTP_UNLOCK_METHOD", cty.StringVal("UNLOCK"),
	).AsString()

	retryMax, err := backendbase.IntValue(
		backendbase.GetAttrEnvDefaultFallback(
			configVal, "retry_max",
			"TF_HTTP_RETRY_MAX", cty.NumberIntVal(2),
		),
	)
	if err != nil {
		return backendbase.ErrorAsDiagnostics(
			fmt.Errorf("invalid retry_max: %s", err),
		)

View on GitHub (pinned to d32a084675)