{"record":{"id":"6a38e9b0faf1a579","repo":"lima-vm/lima","slug":"caching-only-mode-requires-the-cache-directory-to","errorCode":null,"errorMessage":"caching-only mode requires the cache directory to be specified","messagePattern":"caching-only mode requires the cache directory to be specified","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/downloader/downloader.go","lineNumber":199,"sourceCode":"// Download downloads the remote resource into the local path.\n//\n// Download caches the remote resource if WithCache or WithCacheDir option is specified.\n// Local files are not cached.\n//\n// When the local path already exists, Download returns Result with StatusSkipped.\n// (So, the local path cannot be set to /dev/null for \"caching only\" mode.)\n//\n// The local path can be an empty string for \"caching only\" mode.\nfunc Download(ctx context.Context, local, remote string, opts ...Opt) (*Result, error) {\n\tvar o options\n\tif err := o.apply(opts); err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar localPath string\n\tif local == \"\" {\n\t\tif o.cacheDir == \"\" {\n\t\t\treturn nil, errors.New(\"caching-only mode requires the cache directory to be specified\")\n\t\t}\n\t} else {\n\t\tvar err error\n\t\tlocalPath, err = canonicalLocalPath(local)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif _, err := os.Stat(localPath); err == nil {\n\t\t\tlogrus.Debugf(\"file %#q already exists, skipping downloading from %#q (and skipping digest validation)\", localPath, remote)\n\t\t\tres := &Result{\n\t\t\t\tStatus:          StatusSkipped,\n\t\t\t\tValidatedDigest: false,\n\t\t\t}\n\t\t\treturn res, nil\n\t\t} else if !errors.Is(err, os.ErrNotExist) {\n\t\t\treturn nil, err\n\t\t}\n","sourceCodeStart":181,"sourceCodeEnd":217,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/downloader/downloader.go#L181-L217","documentation":"The downloader was invoked in caching-only mode (no local output path) but the Options were never given a cache directory, so there is nowhere to store or find the downloaded artifact. Download refuses to proceed rather than guessing a location.","triggerScenarios":"Calling downloader.Download with local==\"\" while opts.cacheDir is empty — typically via DownloadFile or direct Download calls that omit CacheDir in the downloader Options and pass an empty local path.","commonSituations":"Constructing downloader.New() without setting CacheDir but intending cache-only lookups; tests/utilities that pass \"\" for local to mean \"just use the cache\".","solutions":["Set CacheDir (e.g. ~/.cache/lima) in the downloader Options before calling Download.","Pass a non-empty local path if you actually want a direct download instead of cache-only mode.","Review the code path that constructs the Options to ensure the cache-dir flag/env (e.g. LIMA_HOME) is propagated."],"exampleFix":"// before\nopts := &downloader.Options{}\nres, err := opts.Download(ctx, \"\", \"https://example.com/img.iso\")\n// after\nopts := &downloader.Options{CacheDir: filepath.Join(home, \".cache\", \"lima\")}\nres, err := opts.Download(ctx, \"\", \"https://example.com/img.iso\")","handlingStrategy":"validation","validationCode":"if o.CacheDir == \"\" && local == \"\" {\n    return errors.New(\"cache-only download requires Options.CacheDir to be set\")\n}","typeGuard":null,"tryCatchPattern":"res, err := d.Download(ctx, local, url)\nif err != nil && strings.Contains(err.Error(), \"cache directory to be specified\") {\n    return fmt.Errorf(\"configure CacheDir in downloader options: %w\", err)\n}","preventionTips":["Always set CacheDir when constructing downloader Options.","Add a unit test asserting Options construction populates CacheDir.","Propagate LIMA_HOME-derived paths into the downloader consistently."],"tags":["downloader","cache","configuration","missing-option"],"backgroundTag":"missing-required-option","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}