kopia/kopia · error

unable to set up caching

Error message

unable to set up caching

What it means

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.

Solutions

1. Clear the Kopia cache directory (kopia cache clear or delete ~/.cache/kopia) and retry the connection.
2. Verify the API server base URL matches the one used previously so the cache encryption key derives correctly.
3. Check CachingOptions fields (cache directory path, sizes) for validity; unset them to use defaults.
4. Check filesystem permissions and free space on the cache directory.

Example fix

// before
err := repo.ConnectAPIServer(ctx, si, password, opt, configFile)
// after (clear stale cache first)
opt.CachingOptions.CacheDirectory = "" // reset to default
if err := kopiacli.Run("cache", "clear"); err != nil { return err }
err := repo.ConnectAPIServer(ctx, si, password, opt, configFile)

if fi, err := os.Stat(cacheDir); err == nil && !fi.IsDir() {
    return fmt.Errorf("cache dir %s is not a directory", cacheDir)
}

if err := repo.ConnectAPIServer(ctx, si, password, opt, configFile); err != nil {
    if strings.Contains(err.Error(), "unable to set up caching") {
        os.RemoveAll(cacheDir) // clear stale cache and retry once
    }
    return err
}

When it happens

Trigger: 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.

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

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• error getting caching options
• error opening content cache
• cache directory was not absolute, refusing to delete
• can't open storage
• cannot write to repo connection with permissive cache…

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

Appendix: source

Thrown at repo/api_server_repository.go:29

// NOTE: this structure is persistent on disk may be read/written using
// different versions of Kopia, so it must be backwards-compatible.
//
// Apply appropriate defaults when reading.
type APIServerInfo struct {
	BaseURL                             string `json:"url"`
	TrustedServerCertificateFingerprint string `json:"serverCertFingerprint"`
	LocalCacheKeyDerivationAlgorithm    string `json:"localCacheKeyDerivationAlgorithm,omitempty"`
}

// ConnectAPIServer sets up repository connection to a particular API server.
func ConnectAPIServer(ctx context.Context, configFile string, si *APIServerInfo, password string, opt *ConnectOptions) error {
	lc := LocalConfig{
		APIServer:     si,
		ClientOptions: opt.ApplyDefaults(ctx, "API Server: "+si.BaseURL),
	}

	if err := setupCachingOptionsWithDefaults(ctx, configFile, &lc, &opt.CachingOptions, []byte(si.BaseURL)); err != nil {
		return errors.Wrap(err, "unable to set up caching")
	}

	if err := lc.writeToFile(configFile); err != nil {
		return errors.Wrap(err, "unable to write config file")
	}

	return verifyConnect(ctx, configFile, password)
}

View on GitHub (pinned to 82495e54b5)