{"record":{"id":"42fbe876286a3cc6","repo":"vitessio/vitess","slug":"w-w","errorCode":null,"errorMessage":"%w: %w","messagePattern":"%w: %w","errorType":"exception","errorClass":"errRestoreFatal","httpStatus":null,"severity":"error","filePath":"go/vt/mysqlctl/builtinbackupengine.go","lineNumber":1518,"sourceCode":"\n\t\t\tfor j := range fe.Chunks {\n\t\t\t\tworkItems = append(workItems, restoreWorkItem{\n\t\t\t\t\tfe:       fe,\n\t\t\t\t\tchunk:    &fe.Chunks[j],\n\t\t\t\t\tdestPath: fullPath,\n\t\t\t\t\tname:     fe.Chunks[j].StorageName,\n\t\t\t\t})\n\t\t\t}\n\t\t} else {\n\t\t\tworkItems = append(workItems, restoreWorkItem{\n\t\t\t\tfe:   fe,\n\t\t\t\tname: strconv.Itoa(i),\n\t\t\t})\n\t\t}\n\t}\n\n\tif setupErr != nil {\n\t\treturn fmt.Errorf(\"%w: %w\", errRestoreFatal, setupErr)\n\t}\n\n\t// Phase 2: Dispatch all work items concurrently.\n\tfor _, wi := range workItems {\n\t\tif ctx.Err() != nil {\n\t\t\tbreak\n\t\t}\n\t\tg.Go(func() error {\n\t\t\tselect {\n\t\t\tcase <-ctx.Done():\n\t\t\t\tparams.Logger.Errorf(\"Context canceled or timed out during %q restore\", wi.fe.Name)\n\t\t\t\tbh.RecordError(wi.name, vterrors.Errorf(vtrpcpb.Code_CANCELED, \"context canceled\"))\n\t\t\t\treturn nil\n\t\t\tdefault:\n\t\t\t}\n\n\t\t\tvar err error\n\t\t\tif wi.chunk != nil {","sourceCodeStart":1500,"sourceCodeEnd":1536,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/mysqlctl/builtinbackupengine.go#L1500-L1536","documentation":"During builtin restore, failures in the setup phase are wrapped with errRestoreFatal using Go's multi-%w wrapping. Marking the error fatal tells the restore orchestrator to abort instead of retrying, since a setup failure means the restore cannot proceed at all. The second %w preserves the original cause for inspection.","triggerScenarios":"RestoreFromBackup reaches the end of phase 1 with a non-nil setupErr — e.g. failure to stop mysqld, prepare the data directory, or fetch/validate backup manifest before work items are dispatched.","commonSituations":"Corrupt or incomplete backup manifest in the backup storage; mysqld refusing to shut down within timeout; data directory permission problems on the tablet host.","solutions":["Read the wrapped cause after the colon — it names the actual setup step that failed.","Fix the underlying setup problem (manifest, mysqld shutdown, data dir permissions).","Do not simply retry: fatal errors are fatal because the local state is not restore-safe.","If the cause is a manifest problem, verify the backup is complete or pick an earlier backup."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"err := tabletmanager.RestoreData(ctx, ...)\nif err != nil {\n\tif errors.Is(err, errRestoreFatal) {\n\t\t// abort: do not retry, fix the reported cause first\n\t\treturn err\n\t}\n\t// non-fatal: retry may succeed\n}","preventionTips":["Take backups only after verifying the source tablet is healthy.","Ensure backup storage is reachable and manifests are complete before restore.","Watch for setup-phase logs; failures there are always fatal by design."],"tags":["backup","restore","fatal-error"],"backgroundTag":"restore-fatal-error","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}