{"record":{"id":"c8bf6189840c67bc","repo":"hashicorp/terraform","slug":"failed-to-parse-unlock-address-url-s","errorCode":null,"errorMessage":"failed to parse unlock_address URL: %s","messagePattern":"failed to parse unlock_address URL: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/backend/remote-state/http/backend.go","lineNumber":173,"sourceCode":"\t\t}\n\t\tif lockURL.Scheme != \"http\" && lockURL.Scheme != \"https\" {\n\t\t\treturn backendbase.ErrorAsDiagnostics(\n\t\t\t\tfmt.Errorf(\"lock_address must be HTTP or HTTPS\"),\n\t\t\t)\n\t\t}\n\t}\n\tlockMethod := backendbase.GetAttrEnvDefaultFallback(\n\t\tconfigVal, \"lock_method\",\n\t\t\"TF_HTTP_LOCK_METHOD\", cty.StringVal(\"LOCK\"),\n\t).AsString()\n\n\tvar unlockURL *url.URL\n\tif v := backendbase.GetAttrEnvDefault(configVal, \"unlock_address\", \"TF_HTTP_UNLOCK_ADDRESS\"); !v.IsNull() {\n\t\tvar err error\n\t\tunlockURL, err = url.Parse(v.AsString())\n\t\tif err != nil {\n\t\t\treturn backendbase.ErrorAsDiagnostics(\n\t\t\t\tfmt.Errorf(\"failed to parse unlock_address URL: %s\", err),\n\t\t\t)\n\t\t}\n\t\tif unlockURL.Scheme != \"http\" && unlockURL.Scheme != \"https\" {\n\t\t\treturn backendbase.ErrorAsDiagnostics(\n\t\t\t\tfmt.Errorf(\"unlock_address must be HTTP or HTTPS\"),\n\t\t\t)\n\t\t}\n\t}\n\tunlockMethod := backendbase.GetAttrEnvDefaultFallback(\n\t\tconfigVal, \"unlock_method\",\n\t\t\"TF_HTTP_UNLOCK_METHOD\", cty.StringVal(\"UNLOCK\"),\n\t).AsString()\n\n\tretryMax, err := backendbase.IntValue(\n\t\tbackendbase.GetAttrEnvDefaultFallback(\n\t\t\tconfigVal, \"retry_max\",\n\t\t\t\"TF_HTTP_RETRY_MAX\", cty.NumberIntVal(2),\n\t\t),","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/backend/remote-state/http/backend.go#L155-L191","documentation":"Thrown by the HTTP backend's Configure step when url.Parse() rejects the value supplied via the unlock_address backend argument or the TF_HTTP_UNLOCK_ADDRESS env var. The '%s' carries the underlying net/url parse error, typically an unescaped control character, space, or malformed scheme delimiter. The unlock URL is only parsed when a value is provided (the attribute is optional), so this fires only on an explicitly configured unlock endpoint.","triggerScenarios":"Setting unlock_address to a string with unencoded spaces (e.g. \"http://host/unlock my state\"), missing the scheme (\"//host/unlock\"), a raw IPv6 address without brackets, or any value net/url.Parse cannot accept. Triggered during `terraform init` or any run that re-configures the backend.","commonSituations":"Operators paste a URL containing spaces or query parameters into the unlock_address field without percent-encoding; CI sets TF_HTTP_UNLOCK_ADDRESS from an unescaped template variable; a trailing slash or stray character copied from a wiki.","solutions":["Inspect the exact value in unlock_address (or TF_HTTP_UNLOCK_ADDRESS) and percent-encode any spaces or special characters.","Ensure the value includes an explicit http:// or https:// scheme prefix.","Validate the URL with `echo \"$TF_HTTP_UNLOCK_ADDRESS\" | xargs -n1 python3 -c 'import sys,urllib.parse;urllib.parse.urlparse(sys.argv[1])'` before running terraform.","If the address is generated by a script, run it through url.PathEscape/url.QueryEscape for the path and query portions."],"exampleFix":"// before\nbackend \"http\" {\n  unlock_address = \"http://state.corp/unlock my workspace\"\n}\n// after\nbackend \"http\" {\n  unlock_address = \"http://state.corp/unlock%20my%20workspace\"\n}","handlingStrategy":"validation","validationCode":"// Validate unlock_address before terraform init\nimport (\n  \"fmt\"\n  \"net/url\"\n)\nfunc validateUnlockURL(raw string) error {\n  u, err := url.Parse(raw)\n  if err != nil { return fmt.Errorf(\"unlock_address unparseable: %w\", err) }\n  if u.Scheme != \"http\" && u.Scheme != \"https\" {\n    return fmt.Errorf(\"unlock_address scheme %q not allowed\", u.Scheme)\n  }\n  return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Percent-encode spaces and special chars in any URL set from templates or env vars.","Always include an explicit http:// or https:// scheme.","Lint backend config values in CI with a URL parser before terraform init."],"tags":["config","url-parsing","http-backend","terraform"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}