{"record":{"id":"bbfc7f126799d650","repo":"hashicorp/terraform","slug":"failed-to-create-local-modules-directory-s","errorCode":null,"errorMessage":"failed to create local modules directory: %s","messagePattern":"failed to create local modules directory: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/command/meta_config.go","lineNumber":292,"sourceCode":"\treturn body, diags\n}\n\n// installModules reads a root module from the given directory and attempts\n// recursively to install all of its descendant modules.\n//\n// The given hooks object will be notified of installation progress, which\n// can then be relayed to the end-user. The uiModuleInstallHooks type in\n// this package has a reasonable implementation for displaying notifications\n// via a provided cli.Ui.\nfunc (m *Meta) installModules(ctx context.Context, rootDir, testsDir string, upgrade, installErrsOnly bool, hooks ...initwd.ModuleInstallHook) (abort bool, diags tfdiags.Diagnostics) {\n\tctx, span := tracer.Start(ctx, \"install modules\")\n\tdefer span.End()\n\n\trootDir = m.normalizePath(rootDir)\n\n\terr := os.MkdirAll(m.modulesDir(), os.ModePerm)\n\tif err != nil {\n\t\tdiags = diags.Append(fmt.Errorf(\"failed to create local modules directory: %s\", err))\n\t\treturn true, diags\n\t}\n\n\tloader, err := m.initConfigLoader()\n\tif err != nil {\n\t\tdiags = diags.Append(err)\n\t\treturn true, diags\n\t}\n\n\tinitializer := func(rootMod *configs.Module, walker configs.ModuleWalker) (*configs.Config, tfdiags.Diagnostics) {\n\t\tvariables, diags := backendrun.ParseConstVariableValues(m.VariableValues, rootMod.Variables)\n\t\tctx, ctxDiags := terraform.NewContext(&terraform.ContextOpts{\n\t\t\tParallelism: 1,\n\t\t})\n\t\tdiags = diags.Append(ctxDiags)\n\t\tif diags.HasErrors() {\n\t\t\treturn nil, diags\n\t\t}","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/hashicorp/terraform/blob/c9def3e214014c1188faabfc4a5bde5095139765/internal/command/meta_config.go#L274-L310","documentation":"Raised at the start of module installation when os.MkdirAll fails to create the local modules directory (the .terraform/modules path used to cache downloaded module sources). The wrapped %s is the OS-level mkdir error, typically a permission denial, a read-only filesystem, an invalid path, or insufficient space/inodes.","triggerScenarios":"installModules calls os.MkdirAll(m.modulesDir(), os.ModePerm) and err!=nil. m.modulesDir() resolves to .terraform/modules under the working directory (or TF_DATA_DIR if set). Triggered by: read-only mount, no write permission on cwd, an invalid TF_DATA_DIR, a path whose parent doesn't exist, or a full disk.","commonSituations":"Running `terraform init` in a directory the process cannot write to (e.g. system path, mounted RO image); TF_DATA_DIR pointing to a non-writable or non-existent location; container running as non-root user without volume write perms; filesystem full.","solutions":["Check the wrapped error: if it is a permission error, grant write access to the working directory (or TF_DATA_DIR).","If TF_DATA_DIR is set, ensure the path exists and is writable, or unset it to use the default .terraform.","Run init in a writable working directory.","Free disk space / inodes if the filesystem is full."],"exampleFix":"// before\n// terraform init  -> 'failed to create local modules directory: permission denied'\n\n// after\nchmod -R u+w .terraform\n# or set a writable data dir:\nexport TF_DATA_DIR=/tmp/tfdata && terraform init","handlingStrategy":"validation","validationCode":"// Verify the modules directory is writable before running init\ndir := \".terraform/modules\"\nif v := os.Getenv(\"TF_DATA_DIR\"); v != \"\" {\n    dir = filepath.Join(v, \"modules\")\n}\nif err := os.MkdirAll(dir, 0o755); err != nil {\n    log.Fatalf(\"cannot write modules dir: %v\", err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure the working directory is writable by the user running terraform.","If using TF_DATA_DIR, point it at a writable path.","Run init in a writable working directory in containers/CI.","Check disk space/inodes before large module downloads."],"tags":["terraform","init","modules","filesystem","permissions"],"analyzedSha":"c9def3e214014c1188faabfc4a5bde5095139765","analyzedAt":"2026-08-07T15:39:49.278Z","schemaVersion":2},"datasetVersion":"2026-08-07T20:17:04.800Z"}