{"record":{"id":"630f1911c38db674","repo":"kopia/kopia","slug":"must-have-set-kopia-upgrade-lock-enabled-when-conn","errorCode":null,"errorMessage":"must have set KOPIA_UPGRADE_LOCK_ENABLED when connecting to repository with permissive cache loading","messagePattern":"must have set KOPIA_UPGRADE_LOCK_ENABLED when connecting to repository with permissive cache loading","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"repo/local_config.go","lineNumber":157,"sourceCode":"\n\tif err := json.NewDecoder(f).Decode(&lc); err != nil {\n\t\treturn nil, errors.Wrap(err, \"error decoding config json\")\n\t}\n\n\t// cache directory is stored as relative to config file name, resolve it to absolute.\n\tif lc.Caching != nil {\n\t\tif lc.Caching.CacheDirectory != \"\" && !ospath.IsAbs(lc.Caching.CacheDirectory) {\n\t\t\tlc.Caching.CacheDirectory = filepath.Join(filepath.Dir(fileName), lc.Caching.CacheDirectory)\n\t\t}\n\n\t\t// override cache directory from the environment variable.\n\t\tif cd := os.Getenv(\"KOPIA_CACHE_DIRECTORY\"); cd != \"\" && ospath.IsAbs(cd) {\n\t\t\tlc.Caching.CacheDirectory = cd\n\t\t}\n\t}\n\n\tif lc.PermissiveCacheLoading && os.Getenv(\"KOPIA_UPGRADE_LOCK_ENABLED\") == \"\" {\n\t\treturn nil, errors.New(\"must have set KOPIA_UPGRADE_LOCK_ENABLED when connecting to repository with permissive cache loading\")\n\t}\n\n\treturn &lc, nil\n}\n","sourceCodeStart":139,"sourceCodeEnd":162,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/repo/local_config.go#L139-L162","documentation":"When a local config was written with permissive cache loading, kopia requires the KOPIA_UPGRADE_LOCK_ENABLED environment variable to be set at load time. This proves an upgrade lock is (or may be) in effect, which is the precondition for safely reading the cache without strict coordination. LoadConfigFromFile fails otherwise.","triggerScenarios":"LoadConfigFromFile reading a kopia.config with permissive_cache_loading=true while KOPIA_UPGRADE_LOCK_ENABLED is unset in the environment.","commonSituations":"Running kopia commands via cron/systemd/CI where the env var set during 'kopia server connect' is missing; connecting with permissive cache loading manually without going through the upgrade-lock flow.","solutions":["Export KOPIA_UPGRADE_LOCK_ENABLED=1 before running the kopia command","Reconnect normally (kopia repository connect) to get a non-permissive config if no shared cache is intended","Unset permissive cache loading in the config if the upgrade-lock flow is not in use"],"exampleFix":"# before\n$ kopia snapshot list  # config has permissive cache loading\n// after\n$ export KOPIA_UPGRADE_LOCK_ENABLED=1\n$ kopia snapshot list","handlingStrategy":"validation","validationCode":"if os.Getenv(\"KOPIA_UPGRADE_LOCK_ENABLED\") == \"\" { return errors.New(\"KOPIA_UPGRADE_LOCK_ENABLED must be set for permissive cache loading configs\") }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Ensure KOPIA_UPGRADE_LOCK_ENABLED is exported in all service definitions (cron, systemd, CI) that use the config","Avoid permissive cache loading unless the upgrade-lock workflow is actually deployed"],"tags":["env-var","cache","upgrade-lock"],"backgroundTag":"missing-env-var","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"}