kopia/kopia · critical

error opening repository

Error message

error opening repository

What it means

When the Kopia server initializes its repository asynchronously (InitRepositoryAsync), the user-supplied initializer function failed to open the repository. The underlying cause (bad config, unreachable storage, wrong password, corrupt blob storage) is wrapped with 'error opening repository'. This is a wrapper — the root cause is in the wrapped error.

Solutions

1. Read the wrapped cause beneath 'error opening repository' for the root issue (auth, network, format).
2. Verify repository connectivity manually: run `kopia repository status` with the same config.
3. Check storage credentials (env vars, key files, cloud IAM) and that the storage location still exists.
4. Confirm the config file used by the server points to the intended repository and format version is supported.

Example fix

// before
rep, err := openBlobStorageRepository(ctx, cfg) // cfg missing Password
// after
if cfg.Password == "" {
	return nil, errors.New("storage password not set (KOPA_PASSWORD)")
}
rep, err := openBlobStorageRepository(ctx, cfg)

// before initializing the server, verify the repo opens with the same config
// kopia repository status --config-file <path>

if taskErr != nil {
	var openErr *kopia.OpenError
	if errors.As(taskErr, &openErr) { /* inspect wrapped cause: auth vs network */ }
	log.Printf("repository init failed: %v", taskErr)
}

When it happens

Trigger: Initializer passed to InitRepositoryAsync (e.g. apiServerRepository, filesystem/rclone/blob open) returns an error: bad config file, missing credentials, unreachable cloud storage, incorrect storage passphrase, corrupt repository format.

Common situations: Wrong KOPA_PASSWORD or key in server config; storage bucket/container deleted or credentials rotated; config file points at old cache/storage path; network outage to remote storage; repository created with a newer incompatible format version.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• epoch manager
• error connecting to repository
• error populating repository
• error writing policy manifest
• failed to dump upgrade status

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

Appendix: source

Thrown at internal/server/server.go:924

		defer s.setInitRepositoryTaskID("")

		cctx, cancel := context.WithCancel(ctx)
		defer cancel()

		ctrl.OnCancel(func() {
			cancel()
		})

		// run initializer in cancelable context.
		rep, err := initializer(cctx)

		if cctx.Err() != nil {
			// context canceled
			return errors.New("operation has been canceled")
		}

		if err != nil {
			return errors.Wrap(err, "error opening repository")
		}

		if rep == nil {
			userLog(ctx).Info("Repository not configured.")
		}

		if err = s.SetRepository(ctx, rep); err != nil {
			return errors.Wrap(err, "error connecting to repository")
		}

		return nil
	})

	wg.Wait()

	if wait {
		if ti, ok := s.taskmgr.WaitForTask(ctx, taskID, -1); ok {
			return taskID, ti.Error

View on GitHub (pinned to 82495e54b5)