gastownhall/beads · error

database %q not found on Dolt server at %s:%d

Error message

database %q not found on Dolt server at %s:%d

What it means

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.

Source

Thrown at internal/storage/dolt/errors.go:198

	b.WriteString("Common causes:\n")
	b.WriteString("  - Switched git branches (the Dolt database is runtime state, not in git)\n")
	b.WriteString("  - The server is serving a different data directory than expected\n")
	b.WriteString("  - The server was restarted and is using a different port\n")
	b.WriteString("  - Another project's Dolt server is running on this port\n\n")
	b.WriteString("To diagnose:\n")
	b.WriteString("  bd doctor                  # Check server and database health\n")
	b.WriteString("  bd dolt status             # Show which data directory the server is using")

	if cfg.SyncRemote != "" {
		fmt.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)
	} else {
		b.WriteString("\n\nTip: If this is an existing project, fresh clone, or shared-server recovery, run bd bootstrap first.\n")
		b.WriteString("If bootstrap cannot find the expected remote automatically, set sync.remote\nin .beads/config.yaml and re-run bd bootstrap.\n")
		b.WriteString("Use bd bootstrap --dry-run if you need to confirm the plan before it initializes anything.\n")
		b.WriteString("Use bd init only when creating a brand-new project with no existing .beads data.")
	}

	return errors.New(b.String())
}

// HasBackupFiles checks whether .beads/backup/ contains any JSONL files,
// indicating a prior backup that could be restored (GH#2327).
func HasBackupFiles(beadsDir string) bool {
	if beadsDir == "" {
		return false
	}
	backupDir := filepath.Join(beadsDir, "backup")
	entries, err := os.ReadDir(backupDir)
	if err != nil {
		return false
	}
	for _, e := range entries {
		if !e.IsDir() && strings.HasSuffix(e.Name(), ".jsonl") {
			return true
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd bootstrap` to locate/initialize the expected remote and database.
2. If bootstrap can't find the remote, set sync.remote in .beads/config.yaml and re-run `bd bootstrap`.
3. Verify the server host/port in config actually hosts this project's database (connect and SHOW DATABASES).
4. Only use `bd init` when creating a genuinely brand-new project with no existing .beads data.
5. Use `bd bootstrap --dry-run` to confirm the plan before it initializes anything.

Example fix

// before (config.yaml)
sync:
  remote: git@github.com:org/wrong-repo.git
// after
bd bootstrap --dry-run   # confirm plan
# or set explicitly:
# sync:
#   remote: git@github.com:org/correct-repo.git
bd bootstrap

// confirm the expected DB exists on the server before opening
rows, err := srvConn.Query("SHOW DATABASES LIKE ?", dbName)
if err == nil && !rows.Next() {
    // run bd bootstrap before proceeding
}

var notFound *dolt.DatabaseNotFoundError
if errors.As(err, &notFound) {
    // follow message guidance: run bd bootstrap, check sync.remote
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• failed to open database: %w Hint: %s
• no Dolt server port configured and no server running; run an
• invalid remote URL: %w
• invalid database name %q (use cfg.GetDoltDatabase() to resol
• schema: capture fresh-bootstrap identity: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/f11fabb27dc883ed. Report an issue: GitHub.