hashicorp/terraform · error

detected subdirectory path %q of %q leads outside of the mod

Error message

detected subdirectory path %q of %q leads outside of the module package

What it means

Raised in parseModuleSourceRemote (internal/getmodules/moduleaddrs/source_parsing.go:209). This is the detector-driven counterpart of the previous guard: after NormalizePackageAddress returns an additional subdir (moreSubDir), it is combined with any user subdir and cleaned; if the result still begins with '../', the combined path would escape the package. The code comment notes this would suggest a bug in a go-getter detector, but Terraform catches it defensively.

Source

Thrown at internal/getmodules/moduleaddrs/source_parsing.go:209

		// more helpful error message.
		return addrs.ModuleSourceRemote{}, err
	}

	if moreSubDir != "" {
		switch {
		case subDir != "":
			// The detector's own subdir goes first, because the
			// subdir we were given is conceptually relative to
			// the subdirectory that we just detected.
			subDir = path.Join(moreSubDir, subDir)
		default:
			subDir = path.Clean(moreSubDir)
		}
		if strings.HasPrefix(subDir, "../") {
			// This would suggest a bug in a go-getter detector, but
			// we'll catch it anyway to avoid doing something confusing
			// downstream.
			return addrs.ModuleSourceRemote{}, fmt.Errorf("detected subdirectory path %q of %q leads outside of the module package", subDir, norm)
		}
	}

	return addrs.ModuleSourceRemote{
		Package: addrs.ModulePackage(norm),
		Subdir:  subDir,
	}, nil
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Avoid stacking a shorthand-embedded subdir together with an additional explicit subdir; use one or the other.
2. Switch to a single canonical full URL so the detector does not inject its own subdir.
3. If the source looks valid and minimal, report it as a bug against the relevant detector.

remoteAddr, err := moduleaddrs.ParseModuleSourceRemote(raw)
if err != nil && strings.Contains(err.Error(), "leads outside of the module package") {
    // Detector contributed an escaping subdir; retry with a single canonical URL.
    remoteAddr, err = moduleaddrs.ParseModuleSourceRemote(canonicalURL)
}

When it happens

Trigger: A shorthand/remote detector contributes its own subdir that, when joined with the user's subdir and cleaned, yields a '../' prefix. This is rare and usually indicates either a malformed combined address or a detector returning an escaping path.

Common situations: Combining a shorthand that carries a subdir (e.g. github.com/user/repo//sub) with an additional explicit '//../up' subdir; obscure detector bugs; non-standard source forms.

Related errors

• subdirectory path %q leads outside of the module package
• Error parsing URL: %s
• subdir %q not found
• subdir %q matches multiple paths
• expected on 1 response value, got: %d

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