{"record":{"id":"30739af3f2cdc2b4","repo":"abiosoft/colima","slug":"cannot-fetch-required-directory-w","errorCode":null,"errorMessage":"cannot fetch required directory: %w","messagePattern":"cannot fetch required directory: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"config/files.go","lineNumber":36,"sourceCode":"\t// dir is a func to enable deferring the value of the directory\n\t// until execution time.\n\t// if dir() returns an error, a fatal error is triggered.\n\tdir func() (string, error)\n\n\tcomputedDir *string\n}\n\n// Dir returns the directory path.\n// It ensures the directory is created on the filesystem by calling\n// `mkdir` prior to returning the directory path.\nfunc (r *requiredDir) Dir() string {\n\tif r.computedDir != nil {\n\t\treturn *r.computedDir\n\t}\n\n\tdir, err := r.dir()\n\tif err != nil {\n\t\tlogrus.Fatal(fmt.Errorf(\"cannot fetch required directory: %w\", err))\n\t}\n\n\tr.once.Do(func() {\n\t\tif err := fsutil.MkdirAll(dir, 0755); err != nil {\n\t\t\tlogrus.Fatal(fmt.Errorf(\"cannot make required directory: %w\", err))\n\t\t}\n\t})\n\n\tr.computedDir = &dir\n\treturn dir\n}\n\nvar (\n\tconfigBaseDir = requiredDir{\n\t\tdir: func() (string, error) {\n\t\t\t// colima home explicit config\n\t\t\tdir := os.Getenv(\"COLIMA_HOME\")\n\t\t\tif _, err := os.Stat(dir); err == nil {","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/config/files.go#L18-L54","documentation":"configDir values in config/files.go are requiredDir structs whose Dir() method calls logrus.Fatal when the underlying dir() function errors. The wrapped error comes from environment lookups such as os.UserHomeDir (fails when $HOME is unset), os.UserConfigDir, or os.UserCacheDir. This is a fatal crash that exits the process; it is not returned as an error value to callers.","triggerScenarios":"Invoking any colima command that resolves a config path (essentially all of them) in an environment where $HOME is unset or empty so os.UserHomeDir() returns an error: headless containers, minimal CI images, or launchd/systemd/cron units running with a scrubbed environment.","commonSituations":"Running colima inside Docker or CI containers without HOME; brew services or scheduled jobs with sanitized env; scripts using env -i; a COLIMA_HOME pointing into an inaccessible mount producing stat failures during resolution.","solutions":["Export a valid HOME before running colima: export HOME=/root (or the invoking user's home)","Set COLIMA_HOME to a writable absolute path to bypass home-dir resolution","For cache dir failures, set COLIMA_CACHE_HOME or XDG_CACHE_HOME to a writable location","Fix the service unit or wrapper script to pass HOME and PATH through to the process"],"exampleFix":"# before\ndocker run --rm colima-image colima version   # fatal: cannot fetch required directory\n\n# after\ndocker run --rm -e HOME=/root colima-image colima version","handlingStrategy":"validation","validationCode":"// logrus.Fatal exits the process; validate the environment BEFORE any\n// call that resolves a config/cache/lima directory.\nif os.Getenv(\"HOME\") == \"\" && os.Getenv(\"COLIMA_HOME\") == \"\" {\n    return fmt.Errorf(\"HOME or COLIMA_HOME must be set before running colima\")\n}\nif _, err := os.UserHomeDir(); err != nil {\n    return fmt.Errorf(\"cannot resolve home directory: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"// Not catchable: requiredDir.Dir() calls logrus.Fatal and exits.\n// The only defense is pre-checking HOME/COLIMA_HOME/XDG_* variables\n// before invoking any colima package that resolves directories.","preventionTips":["Always set HOME (or COLIMA_HOME) in containers, CI, and service units that run colima","Audit launchd/systemd/cron plist definitions for EnvironmentVariables entries","Smoke-test 'colima version' in the target environment before relying on it"],"tags":["environment","filesystem","fatal","home-directory"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}