{"record":{"id":"713e651f73c96499","repo":"kopia/kopia","slug":"unable-to-set-up-caching","errorCode":null,"errorMessage":"unable to set up caching","messagePattern":"unable to set up caching","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/api_server_repository.go","lineNumber":29,"sourceCode":"// NOTE: this structure is persistent on disk may be read/written using\n// different versions of Kopia, so it must be backwards-compatible.\n//\n// Apply appropriate defaults when reading.\ntype APIServerInfo struct {\n\tBaseURL                             string `json:\"url\"`\n\tTrustedServerCertificateFingerprint string `json:\"serverCertFingerprint\"`\n\tLocalCacheKeyDerivationAlgorithm    string `json:\"localCacheKeyDerivationAlgorithm,omitempty\"`\n}\n\n// ConnectAPIServer sets up repository connection to a particular API server.\nfunc ConnectAPIServer(ctx context.Context, configFile string, si *APIServerInfo, password string, opt *ConnectOptions) error {\n\tlc := LocalConfig{\n\t\tAPIServer:     si,\n\t\tClientOptions: opt.ApplyDefaults(ctx, \"API Server: \"+si.BaseURL),\n\t}\n\n\tif err := setupCachingOptionsWithDefaults(ctx, configFile, &lc, &opt.CachingOptions, []byte(si.BaseURL)); err != nil {\n\t\treturn errors.Wrap(err, \"unable to set up caching\")\n\t}\n\n\tif err := lc.writeToFile(configFile); err != nil {\n\t\treturn errors.Wrap(err, \"unable to write config file\")\n\t}\n\n\treturn verifyConnect(ctx, configFile, password)\n}\n","sourceCodeStart":11,"sourceCodeEnd":38,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/api_server_repository.go#L11-L38","documentation":"ConnectAPIServer wraps any failure from setupCachingOptionsWithDefaults with this message. setupCachingOptionsWithDefaults initializes local caching options for the API-server config (including possibly unlocking/reading a persistent cache format using a key derived from the base URL). If cache setup fails (unreadable existing cache, decryption failure, invalid caching options), ConnectAPIServer cannot proceed and returns this wrapped error before writing the config file.","triggerScenarios":"Calling ConnectAPIServer (directly or via run/connectAPIServerAndOpen/ConnectAndOpenAPIServer) when setupCachingOptionsWithDefaults fails — e.g. a corrupted persistent cache at the cache directory, a cache format-blob that cannot be decrypted with the key derived from si.BaseURL, or an invalid CachingOptions on the provided options.","commonSituations":"Stale or corrupted cache from a previous Kopia version; connecting with a wrong/changed base URL so the persistent cache key doesn't match; misconfigured --cache-directory or --content-cache-size-mb flags; a read-only or full cache disk.","solutions":["Clear the Kopia cache directory (kopia cache clear or delete ~/.cache/kopia) and retry the connection.","Verify the API server base URL matches the one used previously so the cache encryption key derives correctly.","Check CachingOptions fields (cache directory path, sizes) for validity; unset them to use defaults.","Check filesystem permissions and free space on the cache directory."],"exampleFix":"// before\nerr := repo.ConnectAPIServer(ctx, si, password, opt, configFile)\n// after (clear stale cache first)\nopt.CachingOptions.CacheDirectory = \"\" // reset to default\nif err := kopiacli.Run(\"cache\", \"clear\"); err != nil { return err }\nerr := repo.ConnectAPIServer(ctx, si, password, opt, configFile)","handlingStrategy":"try-catch","validationCode":"if fi, err := os.Stat(cacheDir); err == nil && !fi.IsDir() {\n    return fmt.Errorf(\"cache dir %s is not a directory\", cacheDir)\n}","typeGuard":null,"tryCatchPattern":"if err := repo.ConnectAPIServer(ctx, si, password, opt, configFile); err != nil {\n    if strings.Contains(err.Error(), \"unable to set up caching\") {\n        os.RemoveAll(cacheDir) // clear stale cache and retry once\n    }\n    return err\n}","preventionTips":["Periodically clear the Kopia cache directory after version upgrades.","Keep the API server base URL stable across connections.","Ensure the cache directory is writable and has free space."],"tags":["cache","config","kopia","api-server"],"backgroundTag":"invalid-config-value","analyzedSha":"82495e54b584c1ef6073c9e1be048f57f8aef078","analyzedAt":"2026-09-07T20:35:21.689Z","contentChangedAt":"2026-09-07T20:35:21.689Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}