{"record":{"id":"be65d465291d699a","repo":"hashicorp/terraform","slug":"module-q-was-not-found-please-ensure-that-the-o","errorCode":null,"errorMessage":"module %q was not found.\n\nPlease ensure that the organization and hostname are correct and that your API token for %s is valid.","messagePattern":"module %q was not found\\.\n\nPlease ensure that the organization and hostname are correct and that your API token for (.+?) is valid\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/test.go","lineNumber":416,"sourceCode":"\n\t\tif client, err = tfe.NewClient(cfg); err != nil {\n\t\t\tdiags = diags.Append(tfdiags.Sourceless(\n\t\t\t\ttfdiags.Error,\n\t\t\t\t\"Failed to create the HCP Terraform or Terraform Enterprise client\",\n\t\t\t\tfmt.Sprintf(\n\t\t\t\t\t`Encountered an unexpected error while creating the `+\n\t\t\t\t\t\t`HCP Terraform or Terraform Enterprise client: %s.`, err,\n\t\t\t\t),\n\t\t\t))\n\t\t\treturn nil, nil, diags\n\t\t}\n\t}\n\n\tmodule, err := client.RegistryModules.Read(runner.StoppedCtx, id)\n\tif err != nil {\n\t\t// Then the module doesn't exist, and we can't run tests against it.\n\t\tif err == tfe.ErrResourceNotFound {\n\t\t\terr = 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())\n\t\t}\n\t\tdiags = diags.Append(tfdiags.AttributeValue(\n\t\t\ttfdiags.Error,\n\t\t\tfmt.Sprintf(\"Failed to read module %q\", addr.ForDisplay()),\n\t\t\tfmt.Sprintf(\"Encountered an unexpected error while the module: %s\", err),\n\t\t\tcty.Path{cty.GetAttrStep{Name: \"source\"}}))\n\t\treturn client, nil, diags\n\t}\n\n\t// Enable retries for server errors.\n\tclient.RetryServerErrors(true)\n\n\trunner.appName = client.AppName()\n\tif isValidAppName(runner.appName) {\n\t\trunner.appName = \"HCP Terraform\"\n\t}\n\n\t// Aaaaand I'm done.","sourceCodeStart":398,"sourceCodeEnd":434,"githubUrl":"https://github.com/hashicorp/terraform/blob/d32a084675427f5ac3f7d2868578ef8b2c1dc525/internal/cloud/test.go#L398-L434","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nsource = \"app.terraform.io/wrong-org/vpc/aws\"\n\n// after\nsource = \"app.terraform.io/correct-org/vpc/aws\"","handlingStrategy":"validation","validationCode":"// Validate the module source address and token before running tests\nfunc validateModuleExists(ctx context.Context, client *tfe.Client, id tfe.RegistryModuleID) error {\n    _, err := client.RegistryModules.Read(ctx, id)\n    if err != nil {\n        if errors.Is(err, tfe.ErrResourceNotFound) {\n            return fmt.Errorf(\"module %s/%s/%s not found or token lacks access\", id.Organization, id.Namespace, id.Name)\n        }\n        return fmt.Errorf(\"unexpected error reading module: %w\", err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"// Wrap RegistryModules.Read and check for not-found explicitly\nmodule, err := client.RegistryModules.Read(ctx, id)\nif err != nil {\n    if errors.Is(err, tfe.ErrResourceNotFound) {\n        // handle: module does not exist or token lacks access — do not retry\n        return nil, fmt.Errorf(\"module not found: check org, hostname, and token\")\n    }\n    // other errors may be retryable\n    return nil, err\n}","preventionTips":["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"],"tags":["terraform-cloud","module-registry","not-found","authentication","tfe"],"backgroundTag":null,"analyzedSha":"d32a084675427f5ac3f7d2868578ef8b2c1dc525","analyzedAt":"2026-08-11T18:43:52.779Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}