{"record":{"id":"fa46226471cf9862","repo":"kopia/kopia","slug":"error-opening-repository","errorCode":null,"errorMessage":"error opening repository","messagePattern":"error opening repository","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/server/server.go","lineNumber":924,"sourceCode":"\t\tdefer s.setInitRepositoryTaskID(\"\")\n\n\t\tcctx, cancel := context.WithCancel(ctx)\n\t\tdefer cancel()\n\n\t\tctrl.OnCancel(func() {\n\t\t\tcancel()\n\t\t})\n\n\t\t// run initializer in cancelable context.\n\t\trep, err := initializer(cctx)\n\n\t\tif cctx.Err() != nil {\n\t\t\t// context canceled\n\t\t\treturn errors.New(\"operation has been canceled\")\n\t\t}\n\n\t\tif err != nil {\n\t\t\treturn errors.Wrap(err, \"error opening repository\")\n\t\t}\n\n\t\tif rep == nil {\n\t\t\tuserLog(ctx).Info(\"Repository not configured.\")\n\t\t}\n\n\t\tif err = s.SetRepository(ctx, rep); err != nil {\n\t\t\treturn errors.Wrap(err, \"error connecting to repository\")\n\t\t}\n\n\t\treturn nil\n\t})\n\n\twg.Wait()\n\n\tif wait {\n\t\tif ti, ok := s.taskmgr.WaitForTask(ctx, taskID, -1); ok {\n\t\t\treturn taskID, ti.Error","sourceCodeStart":906,"sourceCodeEnd":942,"githubUrl":"https://github.com/kopia/kopia/blob/82495e54b584c1ef6073c9e1be048f57f8aef078/internal/server/server.go#L906-L942","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause beneath 'error opening repository' for the root issue (auth, network, format).","Verify repository connectivity manually: run `kopia repository status` with the same config.","Check storage credentials (env vars, key files, cloud IAM) and that the storage location still exists.","Confirm the config file used by the server points to the intended repository and format version is supported."],"exampleFix":"// before\nrep, err := openBlobStorageRepository(ctx, cfg) // cfg missing Password\n// after\nif cfg.Password == \"\" {\n\treturn nil, errors.New(\"storage password not set (KOPA_PASSWORD)\")\n}\nrep, err := openBlobStorageRepository(ctx, cfg)","handlingStrategy":"try-catch","validationCode":"// before initializing the server, verify the repo opens with the same config\n// kopia repository status --config-file <path>","typeGuard":null,"tryCatchPattern":"if taskErr != nil {\n\tvar openErr *kopia.OpenError\n\tif errors.As(taskErr, &openErr) { /* inspect wrapped cause: auth vs network */ }\n\tlog.Printf(\"repository init failed: %v\", taskErr)\n}","preventionTips":["Validate storage credentials and KOPA_PASSWORD before server startup","Test repository connectivity with the same config in a pre-flight check","Monitor storage availability; keep the repository format version supported by the binary"],"tags":["repository","storage","kopia","server"],"backgroundTag":"file-not-found","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"}