hashicorp/terraform · error

URL is not a valid GCS URL

Error message

URL is not a valid GCS URL

What it means

Thrown by detectGCS when a source string contains 'googleapis.com/' but splits into fewer than 5 slash-separated parts. The detector expects the form googleapis.com/<segment>/<version>/<bucket>/<object> (parts[0]=host, then version at parts[2], bucket at parts[3], object at parts[4:]). With too few segments there is no room for version+bucket+object, so the address is rejected as an invalid GCS URL.

Solutions

1. Rewrite the source as a full GCS reference including version, bucket, and object, e.g. 'googleapis.com/storage/v1/BUCKET/OBJECT'.
2. Prefer the explicit gcs:: form: 'gcs::https://www.googleapis.com/storage/v1/BUCKET/OBJECT' to skip fragile detection.
3. Verify the path in the GCS browser/console and copy the full object path before pasting.

Example fix

# before (only 4 parts -> invalid)
source = "googleapis.com/storage/v1/my-bucket"

# after (host/version/bucket/object)
source = "googleapis.com/storage/v1/my-bucket/modules/vpc.tar.gz"

// Pre-validate a GCS shorthand has at least host/segment/version/bucket/object (5 parts).
// func validGCSShorthand(src string) error {
//     if !strings.Contains(src, "googleapis.com/") { return nil }
//     if len(strings.Split(src, "/")) < 5 {
//         return fmt.Errorf("GCS source needs googleapis.com/<seg>/<version>/<bucket>/<object>")
//     }
//     return nil
// }

When it happens

Trigger: A module source like 'googleapis.com/storage/v1/bucket' (only 4 parts) or 'googleapis.com/bucket' reaches detectGCS because it contains the trigger substring, but lacks the required version/bucket/object segments.

Common situations: User pastes a partial GCS console URL or a bare bucket name with the googleapis.com host; misremembered GCS path format; copy-paste truncation of the object key.

Related errors

• error parsing GCS URL
• Error parsing URL
• GitHub URLs should be github.com/username/repo
• invalid source address
• URL is not a valid S3 URL

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

Appendix: source

Thrown at internal/getmodules/moduleaddrs/detect_gcs.go:22

package moduleaddrs

import (
	"fmt"
	"net/url"
	"strings"
)

// detectGCS detects strings that seem like schemeless references to
// Google Cloud Storage and translates them into URLs for the "gcs" getter.
func detectGCS(src string) (string, bool, error) {
	if len(src) == 0 {
		return "", false, nil
	}

	if strings.Contains(src, "googleapis.com/") {
		parts := strings.Split(src, "/")
		if len(parts) < 5 {
			return "", false, fmt.Errorf(
				"URL is not a valid GCS URL")
		}
		version := parts[2]
		bucket := parts[3]
		object := strings.Join(parts[4:], "/")

		url, err := url.Parse(fmt.Sprintf("https://www.googleapis.com/storage/%s/%s/%s",
			version, bucket, object))
		if err != nil {
			return "", false, fmt.Errorf("error parsing GCS URL: %s", err)
		}

		return "gcs::" + url.String(), true, nil
	}

	return "", false, nil
}

View on GitHub (pinned to d32a084675)