kopia/kopia · error

must have set KOPIA_UPGRADE_LOCK_ENABLED when connecting to…

Error message

must have set KOPIA_UPGRADE_LOCK_ENABLED when connecting to repository with permissive cache loading

What it means

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.

Solutions

1. Export KOPIA_UPGRADE_LOCK_ENABLED=1 before running the kopia command
2. Reconnect normally (kopia repository connect) to get a non-permissive config if no shared cache is intended
3. Unset permissive cache loading in the config if the upgrade-lock flow is not in use

Example fix

# before
$ kopia snapshot list  # config has permissive cache loading
// after
$ export KOPIA_UPGRADE_LOCK_ENABLED=1
$ kopia snapshot list

if os.Getenv("KOPIA_UPGRADE_LOCK_ENABLED") == "" { return errors.New("KOPIA_UPGRADE_LOCK_ENABLED must be set for permissive cache loading configs") }

When it happens

Trigger: LoadConfigFromFile reading a kopia.config with permissive_cache_loading=true while KOPIA_UPGRADE_LOCK_ENABLED is unset in the environment.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• cache dir marker file too short
• cache dir was not absolute
• cache directory was not absolute, refusing to delete
• can only extend the upgrade-time on an existing lock
• cannot create parent directory for temp file

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/630f1911c38db674. Report an issue: GitHub.

Appendix: source

Thrown at repo/local_config.go:157

	if err := json.NewDecoder(f).Decode(&lc); err != nil {
		return nil, errors.Wrap(err, "error decoding config json")
	}

	// cache directory is stored as relative to config file name, resolve it to absolute.
	if lc.Caching != nil {
		if lc.Caching.CacheDirectory != "" && !ospath.IsAbs(lc.Caching.CacheDirectory) {
			lc.Caching.CacheDirectory = filepath.Join(filepath.Dir(fileName), lc.Caching.CacheDirectory)
		}

		// override cache directory from the environment variable.
		if cd := os.Getenv("KOPIA_CACHE_DIRECTORY"); cd != "" && ospath.IsAbs(cd) {
			lc.Caching.CacheDirectory = cd
		}
	}

	if lc.PermissiveCacheLoading && os.Getenv("KOPIA_UPGRADE_LOCK_ENABLED") == "" {
		return nil, errors.New("must have set KOPIA_UPGRADE_LOCK_ENABLED when connecting to repository with permissive cache loading")
	}

	return &lc, nil
}

View on GitHub (pinned to 82495e54b5)