hashicorp/terraform · error

failed to parse address URL: %s

Error message

failed to parse address URL: %s

What it means

Configure() parses the resolved address with net/url's url.Parse. Although Go's url.Parse is lenient, it returns errors for control characters, invalid escapes, or malformed URLs; such an error is wrapped here with the parse error in %s.

Source

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

	backendbase.Base

	client *httpClient
}

func (b *Backend) Configure(configVal cty.Value) tfdiags.Diagnostics {
	address := backendbase.GetAttrEnvDefaultFallback(
		configVal, "address",
		"TF_HTTP_ADDRESS", cty.StringVal(""),
	).AsString()
	if address == "" {
		return backendbase.ErrorAsDiagnostics(
			fmt.Errorf("address argument is required"),
		)
	}
	updateURL, err := url.Parse(address)
	if err != nil {
		return backendbase.ErrorAsDiagnostics(
			fmt.Errorf("failed to parse address URL: %s", err),
		)
	}
	if updateURL.Scheme != "http" && updateURL.Scheme != "https" {
		return backendbase.ErrorAsDiagnostics(
			fmt.Errorf("address must be HTTP or HTTPS"),
		)
	}

	updateMethod := backendbase.GetAttrEnvDefaultFallback(
		configVal, "update_method",
		"TF_HTTP_UPDATE_METHOD", cty.StringVal("POST"),
	).AsString()

	var lockURL *url.URL
	if v := backendbase.GetAttrEnvDefault(configVal, "lock_address", "TF_HTTP_LOCK_ADDRESS"); !v.IsNull() {
		var err error
		lockURL, err = url.Parse(v.AsString())
		if err != nil {

View on GitHub (pinned to c9def3e214)

Solutions

1. URL-encode the address or fix the malformed component (e.g. replace spaces with %20, encode query params).
2. Validate locally: 'go run -<<' with url.Parse, or just paste into a browser to confirm it's well-formed.
3. Avoid building the URL by concatenation; interpolate from a known-good base + encoded path.

Example fix

// before
address = "https://state.example.com/state/my team.tfstate"

// after
address = "https://state.example.com/state/my%20team.tfstate"

import "net/url"
if _, err := url.Parse(address); err != nil {
    log.Fatalf("address is not a valid URL: %v", err)
}

func isValidURL(s string) bool {
    _, err := url.Parse(s)
    return err == nil
}

When it happens

Trigger: address contains unescaped spaces/control chars, a backslash, unencoded query characters, or otherwise malformed syntax that url.Parse rejects. Triggered during 'terraform init'.

Common situations: URL pasted with spaces, an unencoded fragment/query, a Windows path-style backslash, or a value built by string concatenation that produced invalid escapes.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• address argument is required
• address must be HTTP or HTTPS
• failed to parse lock_address URL: %s
• lock_address must be HTTP or HTTPS
• failed to append certs

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