gastownhall/beads · error

no database connection available (%s)

Error message

no database connection available (%s)

What it means

The batch command requires a database handle to apply its operations. When the command is not being served by the proxied server (usesProxiedServer() is false) and the local store handle is nil, there is no database connection, so the command fails with this error plus a diagnostic hint. It prevents silently batching against nothing.

Source

Thrown at cmd/bd/batch.go:100

NOTE: This is a narrow subset. Commands like 'show', 'list', 'ready', 'sync',
complex create flows, or any flag not listed above are NOT accepted. Use
normal 'bd' subcommands for interactive/read operations.`,
	Args:          cobra.NoArgs,
	SilenceUsage:  true,
	SilenceErrors: false,
	RunE: func(cmd *cobra.Command, args []string) error {
		CheckReadonly("batch")

		evt := metrics.NewCommandEvent("batch")
		defer func() {
			if c := metrics.Global(); c != nil {
				c.CloseEventAndAdd(evt)
			}
		}()

		proxied := usesProxiedServer()
		if !proxied && store == nil {
			return fmt.Errorf("no database connection available (%s)", diagHint())
		}

		filePath, _ := cmd.Flags().GetString("file")
		dryRun, _ := cmd.Flags().GetBool("dry-run")
		commitMsg, _ := cmd.Flags().GetString("message")

		var reader io.Reader
		if filePath != "" {
			f, err := os.Open(filePath) // #nosec G304 -- user-supplied batch file
			if err != nil {
				return fmt.Errorf("open batch file: %w", err)
			}
			defer f.Close()
			reader = f
		} else {
			reader = cmd.InOrStdin()
		}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run 'bd init' in the project root to create the database
2. Start the bd server/proxy if you expect server mode, or unset server config to use direct mode
3. Check the diagHint() suffix in the message — it points at the concrete connection problem
4. Verify you are in the correct directory containing .beads

Example fix

// before
bd batch --file ops.txt   # no DB
// after
bd init
bd batch --file ops.txt

if _, err := os.Stat(".beads"); os.IsNotExist(err) {
	return fmt.Errorf("no beads database here; run 'bd init' first")
}

store != nil || usesProxiedServer()

if err := runBatch(ctx, store, ...); err != nil {
	if strings.Contains(err.Error(), "no database connection") {
		// bd init or start bd server, then retry
	}
	return err
}

When it happens

Trigger: Running 'bd batch' (with --file or stdin) in a context where the local store failed to open or was never initialized, and no proxied server is in use — store == nil.

Common situations: Running batch before 'bd init'; running outside a beads workspace; the database failed to open (corrupt .beads, locked Dolt) so store is nil; server/proxy mode expected but not active.

Related errors

• ErrTransaction
• ErrQuery
• ErrScan
• db: Exists: id must not be empty
• db: CountForPrefix: prefix must not be empty

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