reading project identity (_project_id) from hosted database

Error message

reading project identity (_project_id) from hosted database %q: %w

What it means

In gateway mode the project identity (_project_id) is server-authoritative. resolveInitProjectID wraps the read error with the database name: a failure reading _project_id is surfaced as a transient read problem, distinct from a missing identity, so a flaky connection isn't misdiagnosed as an unprovisioned database.

Source

Thrown at cmd/bd/init.go:146

// MISMATCH. This CreateIfMissing skip is Gateway-only: a non-gateway
// CreateIfMissing:true init against an already-existing database now DOES run
// the verifier (GH#4637 Part A) and fails before reaching this reconciliation.
// A missing server id is a provisioning-contract violation bd will not mint
// over — even when a local id already exists — and a read error is surfaced as
// the transient failure it is, so a flaky connection is not misdiagnosed as an
// unprovisioned database.
//
// Non-gateway (legacy, unchanged): a non-empty localID is kept as-is (readErr
// ignored, exactly as before); otherwise an adopted id wins (another rig already
// chose it; minting a new one would break cross-project verification), else a
// fresh identity is generated.
func resolveInitProjectID(gateway bool, localID, adoptedFromDB, dbName string, readErr error) (value string, changed bool, err error) {
	if gateway {
		if adoptedFromDB != "" {
			return adoptedFromDB, adoptedFromDB != localID, nil
		}
		if readErr != nil {
			return "", false, fmt.Errorf(
				"reading project identity (_project_id) from hosted database %q: %w", dbName, readErr)
		}
		return "", false, fmt.Errorf(
			"hosted database %q has no provisioned project identity (_project_id) -- "+
				"provisioning-contract violation; bd will not mint an identity for a hosted database",
			dbName)
	}
	if localID != "" {
		return localID, false, nil
	}
	if adoptedFromDB != "" {
		return adoptedFromDB, true, nil
	}
	return configfile.GenerateProjectID(), true, nil
}

// shouldConsultInitProjectID reports whether init must read _project_id from the
// database before resolving the local identity.

View on GitHub (pinned to 71377f2769)

Solutions

Retry `bd init` — this is treated as transient, not a provisioning violation
Check connectivity with `bd doctor` / curl the hosted endpoint
Validate gateway credentials and account status
Escalate to the host/admin if the server stays unreachable

Defensive patterns

Strategy: retry

Validate before calling

// Check hosted DB reachability before gateway init
if err := pingHostedDB(dbName); err != nil {
    return fmt.Errorf("hosted DB unreachable, fix connectivity before init: %w", err)
}

Try / catch

if _, _, err := resolveInitProjectID(true, localID, "", dbName, readErr); err != nil {
    if readErr != nil { // transient — back off and retry
        time.Sleep(time.Second)
        return resolveInitProjectID(true, localID, "", dbName, readProjectIDFromDB())
    }
    return err
}

Prevention

Verify connectivity to the hosted server before init
Keep gateway credentials valid
Treat _project_id read errors as transient — don't mint local identities to work around them
Run `bd doctor` when in doubt

When it happens

Trigger: `bd init` with a gateway connection (shouldConsultInitProjectID always consults in gateway mode) where adoptedFromDB is empty and the _project_id read returns an error (network, auth, server, query failure) — passed as readErr.

Common situations: Network blips to the hosted server; expired credentials; server outage/maintenance; proxy/DNS failures — same transient causes as the prefix read error (init.go:103).

Related errors

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