module %q was not found. Please ensure that the organizatio

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

terraform test reads the private-registry module via RegistryModules.Read; a 404 is wrapped as 'module not found'. Because HCP/TFE returns 404 both for non-existent modules and for ones the token cannot access, this can also indicate an auth/permission problem.

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 c9def3e214)

Solutions

Confirm the module is published in the private registry under the exact org/namespace/name/provider.
Verify the API token is valid and scoped to that organization.
Re-check the hostname in the source address.
Run terraform login <hostname> to refresh the token.

Example fix

# before: module not published / wrong org -> module "..." was not found
# after: publish the module to the private registry and confirm token scope
terraform login app.terraform.io
terraform test

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: confirm the module exists in the private registry
if _, err := client.RegistryModules.Read(ctx, id); err != nil {
    if errors.Is(err, tfe.ErrResourceNotFound) {
        return fmt.Errorf("module not found or token lacks access: %s", addr.ForDisplay())
    }
    return err
}

Type guard

func isModuleNotFound(err error) bool {
    return errors.Is(err, tfe.ErrResourceNotFound)
}

Try / catch

module, err := client.RegistryModules.Read(ctx, id)
if err != nil {
    if errors.Is(err, tfe.ErrResourceNotFound) {
        // could be missing OR unauthorized (404 hides both); verify token scope and publishing
    }
}

Prevention

Publish the module to the private registry under the exact org/namespace/name/provider
Use a token scoped to the right organization
Run terraform login <hostname> to refresh credentials

When it happens

Trigger: Module address is wrong (org/namespace/name/provider mismatch), the module is not published to the private registry, or the API token lacks read access to that module.

Common situations: Typo in the module source, module not yet published/uploaded, token for the wrong organization, or token without private-registry read scope.

Related errors

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