gastownhall/beads · error

reading issue_prefix from hosted database %q: %w

Error message

reading issue_prefix from hosted database %q: %w

What it means

In gateway (hosted) mode, the issue_prefix is provisioned server-side and init must read it from the hosted database. resolveInitIssuePrefix wraps the read error with the database name: a read failure is surfaced as transient rather than misdiagnosed as an unprovisioned database.

Source

Thrown at cmd/bd/init.go:103

// one exists, return "" — there is nothing to set, because init must not clobber
// a prefix a shared database already carries. readErr is ignored here, exactly
// as legacy init ignored it. Gateway: the prefix is server-provisioned, so an
// existing value is adopted. A missing value is a provisioning-contract
// violation — bd will not choose a prefix for a hosted database — but only when
// the read genuinely succeeded and returned empty: a read error means we could
// not consult the server, so it is surfaced as the transient failure it is
// rather than misdiagnosed as an unprovisioned database.
//
// Whether the prefix may be WRITTEN is not decided here: that is the same
// question as whether the substrate is unidentified, and issueops.Bootstrapper
// answers it inside the transaction it writes in.
func resolveInitIssuePrefix(gateway bool, existing, dbName, prefix string, readErr error) (value string, err error) {
	if existing != "" {
		return "", nil
	}
	if gateway {
		if readErr != nil {
			return "", fmt.Errorf(
				"reading issue_prefix from hosted database %q: %w", dbName, readErr)
		}
		return "", fmt.Errorf(
			"hosted database %q has no issue_prefix -- provisioning-contract violation; "+
				"bd will not choose one for a hosted database (re-provision server-side, then re-run init)",
			dbName)
	}
	return strings.ReplaceAll(prefix, ".", "_"), nil
}

// resolveInitProjectID decides init's project identity by reconciling the local
// metadata.json id (localID; "" when none is set yet) with the _project_id read
// from the database (adoptedFromDB; "" when absent or not consulted). readErr is
// the error, if any, from that read. changed reports whether the resolved id
// differs from localID, so the caller can surface the reconciliation.
//
// Gateway: the hosted database's identity is server-authoritative, so an adopted
// server id always wins and is reconciled onto local even when localID is already

View on GitHub (pinned to 71377f2769)

Solutions

1. Retry `bd init` — the code treats this as a transient read failure, not a provisioning problem
2. Verify connectivity to the hosted server (ping/curl the endpoint, check `bd doctor`)
3. Check gateway credentials are valid and not expired
4. If it persists, contact the host/admin: the server may be down or your database misconfigured

// Before init, confirm the hosted DB is reachable
// e.g. curl or dolt sql against the gateway endpoint; or run `bd doctor`

if _, err := resolveInitIssuePrefix(true, "", dbName, "", readErr); err != nil {
    if readErr != nil { // transient read failure — retry with backoff
        time.Sleep(time.Second)
        return resolveInitIssuePrefix(true, "", dbName, "", readPrefixFromDB())
    }
    return err
}

When it happens

Trigger: `bd init` with a gateway-managed connection where the existing prefix is empty and the read of issue_prefix from the hosted DB returns an error (network failure, auth failure, server down, query error) — passed in as readErr.

Common situations: Flaky network to the hosted Dolt server; expired/invalid credentials; server maintenance or outage; DNS or proxy failures reaching the hosted endpoint.

Related errors

• reading project identity (_project_id) from hosted database
• hosted database %q has no issue_prefix -- provisioning-contr
• hosted database %q has no provisioned project identity (_pro
• failed to read response: %w
• get dependency records: rows: %w

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