module was not found. Please ensure that the organization…

Error message

module %q was not found.

Please ensure that the organization and hostname are correct and that your API token for %s is valid.

What it means

Thrown by the test runner's client() method when RegistryModules.Read returns tfe.ErrResourceNotFound for the module identified by the source address. Terraform wraps it with guidance to check the organization, hostname, and API token validity. This prevents attempting to run tests against a module that does not exist in or is not accessible from the registry.

Solutions

Verify the module exists at the registry path: check app.terraform.io/<org>/<name>/overview or the TFE registry UI
Confirm the API token (TF_TOKEN_<hostname> or TFE_TOKEN) is valid and has read access to the organization
Correct the module source address to exactly match the organization, name, and provider in the registry
If using a private TFE instance, ensure the hostname in the source matches the TFE installation URL

Example fix

// before
source = "app.terraform.io/wrong-org/vpc/aws"

// after
source = "app.terraform.io/correct-org/vpc/aws"

Defensive patterns

Strategy: validation

Validate before calling

// Validate the module source address and token before running tests
func validateModuleExists(ctx context.Context, client *tfe.Client, id tfe.RegistryModuleID) error {
    _, err := client.RegistryModules.Read(ctx, id)
    if err != nil {
        if errors.Is(err, tfe.ErrResourceNotFound) {
            return fmt.Errorf("module %s/%s/%s not found or token lacks access", id.Organization, id.Namespace, id.Name)
        }
        return fmt.Errorf("unexpected error reading module: %w", err)
    }
    return nil
}

Try / catch

// Wrap RegistryModules.Read and check for not-found explicitly
module, err := client.RegistryModules.Read(ctx, id)
if err != nil {
    if errors.Is(err, tfe.ErrResourceNotFound) {
        // handle: module does not exist or token lacks access — do not retry
        return nil, fmt.Errorf("module not found: check org, hostname, and token")
    }
    // other errors may be retryable
    return nil, err
}

Prevention

Verify the module source address components (organization, name, provider) match the registry exactly
Ensure the API token has read access to the target organization
Use terraform login to set up credentials for the correct hostname before running tests
Check module visibility (private vs public) matches your token's permissions

When it happens

Trigger: client.RegistryModules.Read(runner.StoppedCtx, id) returns tfe.ErrResourceNotFound, where id is a tfe.RegistryModuleID derived from the module source address (addr). Occurs when the module path is wrong, the organization doesn't exist, the hostname is incorrect, or the API token lacks read access to the module.

Common situations: Typo or wrong organization name in the module source address; module is private and the configured API token does not have access; using the wrong registry hostname; module has not been published to the registry yet; namespace mismatch between source address and registry.

Related errors

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

Appendix: source

Thrown at internal/cloud/test.go:416

		if client, err = tfe.NewClient(cfg); err != nil {
			diags = diags.Append(tfdiags.Sourceless(
				tfdiags.Error,
				"Failed to create the HCP Terraform or Terraform Enterprise client",
				fmt.Sprintf(
					`Encountered an unexpected error while creating the `+
						`HCP Terraform or Terraform Enterprise client: %s.`, err,
				),
			))
			return nil, nil, diags
		}
	}

	module, err := client.RegistryModules.Read(runner.StoppedCtx, id)
	if err != nil {
		// Then the module doesn't exist, and we can't run tests against it.
		if err == tfe.ErrResourceNotFound {
			err = fmt.Errorf("module %q was not found.\n\nPlease ensure that the organization and hostname are correct and that your API token for %s is valid.", addr.ForDisplay(), addr.Package.Host.ForDisplay())
		}
		diags = diags.Append(tfdiags.AttributeValue(
			tfdiags.Error,
			fmt.Sprintf("Failed to read module %q", addr.ForDisplay()),
			fmt.Sprintf("Encountered an unexpected error while the module: %s", err),
			cty.Path{cty.GetAttrStep{Name: "source"}}))
		return client, nil, diags
	}

	// Enable retries for server errors.
	client.RetryServerErrors(true)

	runner.appName = client.AppName()
	if isValidAppName(runner.appName) {
		runner.appName = "HCP Terraform"
	}

	// Aaaaand I'm done.

View on GitHub (pinned to d32a084675)