What causes "unlock_address must be HTTP or HTTPS" in hashicorp/terraform?

Prefix unlock_address with http:// or https:// (https:// strongly preferred).

unlock_address must be HTTP or HTTPS

Error message

unlock_address must be HTTP or HTTPS

What it means

Raised in Configure after unlock_address parses successfully but its scheme is neither http nor https. The backend only speaks HTTP/HTTPS for state I/O, so file://, ftp://, or a schemeless host are rejected outright. Distinct from error 240 which fires when parsing itself fails.

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 c9def3e214)

Solutions

Prefix unlock_address with http:// or https:// (https:// strongly preferred).
If you intended a plain hostname, rewrite as "https://state.corp/unlock".
Double-check the TF_HTTP_UNLOCK_ADDRESS env var is not inherited from a different tool expecting a different scheme.

Example fix

// before
unlock_address = "state.corp/unlock"
// after
unlock_address = "https://state.corp/unlock"

Defensive patterns

Strategy: validation

Validate before calling

import "net/url"
func assertHTTPScheme(raw string) error {
  u, err := url.Parse(raw)
  if err != nil { return err }
  if u.Scheme != "http" && u.Scheme != "https" {
    return fmt.Errorf("scheme must be http or https, got %q", u.Scheme)
  }
  return nil
}

Prevention

Standardize all state endpoints on https://.
Reject config submissions whose URLs lack a scheme in code review.
Generate URLs from a single typed config struct rather than free-form strings.

When it happens

Trigger: unlock_address set to a non-HTTP scheme such as "file:///tmp/unlock", "ftp://host/unlock", or a bare "state.corp/unlock" that url.Parse interprets as scheme="state.corp". Triggered during backend Configure at `terraform init`.

Common situations: Typo dropping the scheme prefix; copy-paste from an internal doc that lists just the host/path; accidentally prefixing with the workspace name instead of http://.

Related errors

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