{"record":{"id":"02f62773189d2ae5","repo":"gastownhall/beads","slug":"register-backup-remote-w","errorCode":null,"errorMessage":"register backup remote: %w","messagePattern":"register backup remote: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/store.go","lineNumber":1324,"sourceCode":"\tsyncDB, err := s.oneShotConn(0)\n\tif err != nil {\n\t\treturn err\n\t}\n\tdefer syncDB.Close()\n\n\t// Register as a backup remote (idempotent — remove first if exists).\n\t_ = versioncontrolops.BackupRemove(ctx, s.db, backupName)\n\tif err := versioncontrolops.BackupAdd(ctx, s.db, backupName, backupURL); err != nil {\n\t\t// Another backup (e.g. \"default\" registered by `bd backup init`) may\n\t\t// already point to this URL. In that case, sync using the existing\n\t\t// remote name rather than failing.\n\t\tif conflict := versioncontrolops.ExtractAddressConflictName(err); conflict != \"\" {\n\t\t\tif syncErr := versioncontrolops.BackupSync(ctx, syncDB, conflict); syncErr != nil {\n\t\t\t\treturn fmt.Errorf(\"sync to backup: %w\", syncErr)\n\t\t\t}\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\"register backup remote: %w\", err)\n\t}\n\tif err := versioncontrolops.BackupSync(ctx, syncDB, backupName); err != nil {\n\t\treturn fmt.Errorf(\"sync to backup: %w\", err)\n\t}\n\treturn nil\n}\n\n// RestoreDatabase restores the database from a Dolt backup at dir.\n// When force is true, an existing database is overwritten.\nfunc (s *DoltStore) RestoreDatabase(ctx context.Context, dir string, force bool) error {\n\tinfo, err := os.Stat(dir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"backup source does not exist: %w\", err)\n\t}\n\tif !info.IsDir() {\n\t\treturn fmt.Errorf(\"backup source is not a directory: %s\", dir)\n\t}\n","sourceCodeStart":1306,"sourceCodeEnd":1342,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/store.go#L1306-L1342","documentation":"BackupDatabase called versioncontrolops.BackupAdd to register the destination directory as a file:// Dolt backup remote, and the registration failed with an error that was not an address conflict (no recoverable existing remote name was extractable). The backup aborts before any data is synced.","triggerScenarios":"BackupAdd(ctx, s.db, backupName, backupURL) returned a non-conflict error — the Dolt SQL layer rejected the backup registration, e.g. the remote name is invalid, the SQL connection to s.db failed, or the server does not support the backup operation in this mode.","commonSituations":"Embedded vs server mode mismatch where backup operations are unavailable; invalid backup name characters; Dolt version too old for the backup remote API; connection failure to the store's database at registration time.","solutions":["Read the wrapped BackupAdd error — it names the concrete Dolt/SQL failure; fix that cause first.","If the real problem is an existing remote at the same URL that failed conflict extraction, list existing backups (`dolt backup -v`) and remove the stale one, then retry.","Confirm your Dolt server/version supports backup remotes (CALL DOLT_BACKUP); upgrade Dolt if the call is unknown.","Check connectivity to s.db — registration goes over the SQL connection, so connection errors surface here."],"exampleFix":"// before: stale remote blocks registration\n// after: remove the stale remote then retry\n_, _ = db.ExecContext(ctx, \"CALL DOLT_BACKUP('remove', 'default')\")\nerr := store.BackupDatabase(ctx, dir)","handlingStrategy":"try-catch","validationCode":"// probe that backup registration is supported before calling\nif err := db.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"cannot reach dolt to register backup: %w\", err)\n}\n// list existing backups first to avoid conflicts\nrows, _ := db.Query(\"CALL DOLT_BACKUP('-v')\")","typeGuard":null,"tryCatchPattern":"if err := store.BackupDatabase(ctx, dir); err != nil {\n    if strings.Contains(err.Error(), \"register backup remote\") {\n        // remove stale remotes then retry once\n        _, _ = db.ExecContext(ctx, \"CALL DOLT_BACKUP('remove', 'beads-backup')\")\n        err = store.BackupDatabase(ctx, dir)\n    }\n}","preventionTips":["List existing Dolt backup remotes before registering; remove stale ones first.","Use simple remote names (letters, digits, dashes) to avoid name-validation failures.","Confirm your Dolt version supports CALL DOLT_BACKUP before scripting around it.","Register backups against a healthy s.db connection — registration is a SQL operation."],"tags":["dolt","backup","remote","registration"],"backgroundTag":"backup-remote-registration-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}