Terraform Error: “remote package address may not have a sub-path”

Introduction

This article addresses a module source parsing error that occurs during Terraform runs. The error happens when you reference a module in a subdirectory of a version control system (VCS) repository or an archive-based module source. This guidance applies to all editions of Terraform, including the CLI, HCP Terraform, and Terraform Enterprise.

Problem

When running Terraform commands like terraform init, the operation fails with the following error message:

terraform: Failed to parse source address: tfe_hostname/tfe/monitoring/aws//modules/aws/sns: error="remote package address may not have a sub-path"

This error indicates an incorrect format for the module source attribute when attempting to reference a module located in a subdirectory.

Cause

Terraform uses a double-slash (//) in a module source address to indicate that the module is in a subdirectory of a repository or archive. However, this syntax is only valid for specific source types that Terraform can identify through a protocol prefix (e.g., git::, https::).

When the source address lacks a recognized prefix, Terraform interprets it as a Terraform Registry address, which does not support the // subdirectory syntax. The error occurs because Terraform cannot parse the address as a valid registry module while it contains a sub-path indicator.

The following tables summarize when to use the // syntax.

Sources that require // for subdirectories:

Sources that do not support //:

Using // with an unsupported source type will result in the "may not have a sub-path" error.

Solutions

Here are several solutions to resolve this error, depending on your module source.

Solution 1: Add a VCS prefix to the source address

If your module is hosted in a Git repository, add the git:: prefix to the source address. This prefix tells Terraform how to interpret the address and correctly handle the // for the subdirectory.

For example, correct the invalid source:

# ...
module "example" {
  ## Invalid source without a protocol prefix
  source = "tfe_hostname/tfe/monitoring/aws//modules/aws/sns"
}
# ...

By adding the git:: prefix and the .git extension, you create a valid source address:

# ...
module "example" {
  ## Corrected source with git:: prefix and .git extension
  source = "git::https://tfe_hostname/tfe/monitoring/aws.git//modules/aws/sns"
}
# ...

You can also specify a branch or tag using the ref argument after the subdirectory path.

# ...
module "example" {
  source = "git::https://tfe_hostname/repo.git//modules/sns?ref=main"
}
# ...

Solution 2: Use a separate repository for the module

To avoid the complexity of subdirectory paths, you can move the module into its own dedicated repository. This simplifies the source address and removes the need for the // syntax entirely.

# ...
module "example" {
  source = "git::https://tfe_hostname/modules/aws-sns.git"
}
# ...

Verification

After applying one of the solutions, run terraform init again to confirm that Terraform can now download the module correctly. A successful init will show the module being installed.

$ terraform init

Initializing modules...
- example in .terraform/modules/example

Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/aws...
- Installing hashicorp/aws v5.31.0...
- Installed hashicorp/aws v5.31.0 (signed by HashiCorp)

Terraform has been successfully initialized!

After a successful initialization, run terraform plan to ensure there are no further configuration errors.

Additional Information

• Terraform Docs: Module Sources
• Modules in Package Sub-directories
• Generic Git Repository Module Source
• Module Versioning with the ref Argument