hosted database %q has no issue_prefix -- provisioning-contr

Error message

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)

What it means

In gateway mode the issue_prefix must be provisioned server-side before init. If the read succeeds but the hosted database has no issue_prefix, init refuses to invent one — this is flagged as a provisioning-contract violation, with the database name in the message.

Source

Thrown at cmd/bd/init.go:106

// 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
// set. A re-init or orchestrator-preseeded workspace must not keep a stale local
// id: for Gateway specifically, init's CreateIfMissing:true open still skips the
// storage identity verifier (store.go verifyProjectIdentity/newServerMode — see

View on GitHub (pinned to 71377f2769)

Solutions

Re-provision the database server-side (per the error: re-provision, then re-run init) so issue_prefix exists
Verify you're pointing at the right hosted database name (--database / connection config)
If you're the host operator, set the prefix in the hosted DB's config table: issue_prefix = <prefix>
Confirm the hosted backend version supports prefix provisioning

Example fix

// before: gateway DB missing prefix
bd init  # fails: hosted database "xyz" has no issue_prefix -- provisioning-contract violation
// after: re-provision server-side (or have the host set issue_prefix), then
bd init

Defensive patterns

Strategy: validation

Validate before calling

// Before gateway init, verify the hosted DB carries a prefix
prefix, err := readConfigFromHostedDB(dbName, "issue_prefix")
if err != nil { return err }
if strings.TrimSpace(prefix) == "" {
    return fmt.Errorf("hosted DB %s is unprovisioned: re-provision server-side first", dbName)
}

Prevention

Always provision hosted databases through the server-side flow, not manual creation
Confirm the --database name matches the provisioned DB before init
After any host-side reset, re-provision before clients run init
Never let bd choose a prefix for hosted DBs — set it deliberately server-side

When it happens

Trigger: `bd init` with a gateway connection against a hosted database whose issue_prefix config is empty/missing after a successful read — i.e. the server-side provisioning step never ran or was wiped.

Common situations: Database created out-of-band (manual SQL/API creation) without the provisioning flow; a host-side wipe/reset that dropped the config; pointing bd at the wrong database name; an old backend version that predates prefix provisioning.

Related errors

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