{"record":{"id":"f11fabb27dc883ed","repo":"gastownhall/beads","slug":"database-q-not-found-on-dolt-server-at-s-d","errorCode":null,"errorMessage":"database %q not found on Dolt server at %s:%d","messagePattern":"database %q not found on Dolt server at (.+?):(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dolt/errors.go","lineNumber":198,"sourceCode":"\tb.WriteString(\"Common causes:\\n\")\n\tb.WriteString(\"  - Switched git branches (the Dolt database is runtime state, not in git)\\n\")\n\tb.WriteString(\"  - The server is serving a different data directory than expected\\n\")\n\tb.WriteString(\"  - The server was restarted and is using a different port\\n\")\n\tb.WriteString(\"  - Another project's Dolt server is running on this port\\n\\n\")\n\tb.WriteString(\"To diagnose:\\n\")\n\tb.WriteString(\"  bd doctor                  # Check server and database health\\n\")\n\tb.WriteString(\"  bd dolt status             # Show which data directory the server is using\")\n\n\tif cfg.SyncRemote != \"\" {\n\t\tfmt.Fprintf(&b, \"\\n\\nTip: sync.remote is configured (%s).\\nRun bd bootstrap to recover from the remote or confirm what bootstrap will do with --dry-run.\", cfg.SyncRemote)\n\t} else {\n\t\tb.WriteString(\"\\n\\nTip: If this is an existing project, fresh clone, or shared-server recovery, run bd bootstrap first.\\n\")\n\t\tb.WriteString(\"If bootstrap cannot find the expected remote automatically, set sync.remote\\nin .beads/config.yaml and re-run bd bootstrap.\\n\")\n\t\tb.WriteString(\"Use bd bootstrap --dry-run if you need to confirm the plan before it initializes anything.\\n\")\n\t\tb.WriteString(\"Use bd init only when creating a brand-new project with no existing .beads data.\")\n\t}\n\n\treturn errors.New(b.String())\n}\n\n// HasBackupFiles checks whether .beads/backup/ contains any JSONL files,\n// indicating a prior backup that could be restored (GH#2327).\nfunc HasBackupFiles(beadsDir string) bool {\n\tif beadsDir == \"\" {\n\t\treturn false\n\t}\n\tbackupDir := filepath.Join(beadsDir, \"backup\")\n\tentries, err := os.ReadDir(backupDir)\n\tif err != nil {\n\t\treturn false\n\t}\n\tfor _, e := range entries {\n\t\tif !e.IsDir() && strings.HasSuffix(e.Name(), \".jsonl\") {\n\t\t\treturn true\n\t\t}\n\t}","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dolt/errors.go#L180-L216","documentation":"databaseNotFoundError builds a rich error stating the database %q was not found on the Dolt server at host:port. It fires when a server-mode connection opens successfully but the expected database does not exist on that server. The returned message includes remediation guidance: run `bd bootstrap` for existing projects/fresh clones/shared-server recovery, set sync.remote in .beads/config.yaml if the remote can't be auto-found, and use `bd init` only for brand-new projects.","triggerScenarios":"Calling an open/read path that calls openServerConnection when the Dolt server at the configured host:port has no database with the expected name (e.g. database was dropped, wrong port, wrong server, or never initialized on this server).","commonSituations":"Pointing .beads config at the wrong sql-server host/port; fresh clone before running bd bootstrap; a shared server whose database was never created for this project; database renamed or dropped on the server.","solutions":["Run `bd bootstrap` to locate/initialize the expected remote and database.","If bootstrap can't find the remote, set sync.remote in .beads/config.yaml and re-run `bd bootstrap`.","Verify the server host/port in config actually hosts this project's database (connect and SHOW DATABASES).","Only use `bd init` when creating a genuinely brand-new project with no existing .beads data.","Use `bd bootstrap --dry-run` to confirm the plan before it initializes anything."],"exampleFix":"// before (config.yaml)\nsync:\n  remote: git@github.com:org/wrong-repo.git\n// after\nbd bootstrap --dry-run   # confirm plan\n# or set explicitly:\n# sync:\n#   remote: git@github.com:org/correct-repo.git\nbd bootstrap","handlingStrategy":"validation","validationCode":"// confirm the expected DB exists on the server before opening\nrows, err := srvConn.Query(\"SHOW DATABASES LIKE ?\", dbName)\nif err == nil && !rows.Next() {\n    // run bd bootstrap before proceeding\n}","typeGuard":null,"tryCatchPattern":"var notFound *dolt.DatabaseNotFoundError\nif errors.As(err, &notFound) {\n    // follow message guidance: run bd bootstrap, check sync.remote\n}","preventionTips":["Run bd bootstrap after fresh clones or server recovery","Pin sync.remote in .beads/config.yaml for shared servers","Verify host:port points at the correct sql-server","Use bd bootstrap --dry-run to preview initialization"],"tags":["dolt","database","configuration","server","bootstrap"],"backgroundTag":"database-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}