gastownhall/beads · critical

PROJECT IDENTITY MISMATCH — refusing to connect Local pro

Error message

PROJECT IDENTITY MISMATCH — refusing to connect

  Local project ID (metadata.json):  %s
  Database %q project ID:            %s

The team server is serving a DIFFERENT project's database.
This can happen when:
  - --database (or a --db name override) points at another project
  - the configured dolt_database was repointed after 'bd init'
  - the operator re-provisioned this database for another project

Check dolt_database in .beads/metadata.json and any --database/--db
override. 'bd init --team-server' re-adopts the provisioned identity
and never writes to the shared database, so it is safe to re-run.

What it means

A hard refusal to connect because the database's stored project ID does not match the local project ID in .beads/metadata.json. The team server is serving a different project's database; writing would corrupt another project's data, so bd aborts with a diagnostic explaining the likely causes and the safe re-adoption path ('bd init --team-server').

Source

Thrown at internal/storage/uow/team_server_schema.go:82

	// the metadata table exists and a failure here is a real fault, not the
	// legacy-database case verifyProjectIdentity tolerates.
	dbProjectID, err := issueops.GetMetadataInTx(ctx, conn, "_project_id")
	if err != nil {
		return fmt.Errorf("uow: team-server identity check on database %q: %w", database, err)
	}
	// Unlike verifyProjectIdentity, an absent stored identity is NOT tolerated
	// here. adoptTeamServerIdentity refuses to attach to a bts database that
	// has no metadata._project_id at all, so for a team-server database this
	// is an already-invalid state rather than a legacy one — and soft-skipping
	// it would mean deleting one row from the shared database silently
	// disables this guard for every client.
	if dbProjectID == "" {
		return fmt.Errorf(
			"uow: database %q has no project identity (metadata._project_id) — the schema is managed by beads-team-server; ask your operator to provision it with 'bts init' (or heal an older bts database with 'bts migrate')",
			database)
	}
	if dbProjectID != expectedProjectID {
		return fmt.Errorf(
			"PROJECT IDENTITY MISMATCH — refusing to connect\n\n"+
				"  Local project ID (metadata.json):  %s\n"+
				"  Database %q project ID:            %s\n\n"+
				"The team server is serving a DIFFERENT project's database.\n"+
				"This can happen when:\n"+
				"  - --database (or a --db name override) points at another project\n"+
				"  - the configured dolt_database was repointed after 'bd init'\n"+
				"  - the operator re-provisioned this database for another project\n\n"+
				"Check dolt_database in .beads/metadata.json and any --database/--db\n"+
				"override. 'bd init --team-server' re-adopts the provisioned identity\n"+
				"and never writes to the shared database, so it is safe to re-run.",
			expectedProjectID, database, dbProjectID)
	}
	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Check dolt_database in .beads/metadata.json and any --database/--db override; point back at your project's database
2. If you intend to adopt the provisioned database, re-run 'bd init --team-server' (read-only re-adoption, safe to re-run)
3. If the operator re-provisioned the database, coordinate re-initialization of local metadata
4. Do not edit _project_id manually in the shared database

Example fix

// before
bd sync --database beads-other  # PROJECT IDENTITY MISMATCH
// after
bd init --team-server --database beads   # re-adopt correct provisioned identity
bd sync --database beads

-- preflight: compare local vs database identity before any write
# local:
jq -r .default_database .beads/metadata.json; cat .beads/metadata.json | grep -i project
# database:
SELECT value FROM metadata WHERE `key` = '_project_id';  -- must equal local project ID

func isIdentityMismatch(err error) bool {
  return err != nil && strings.Contains(err.Error(), "PROJECT IDENTITY MISMATCH")
}

err := bdSync(ctx)
if isIdentityMismatch(err) {
  // never retry blindly — you may write to another project's database
  return fmt.Errorf("fix --database/dolt_database or re-adopt with 'bd init --team-server': %w", err)
}

When it happens

Trigger: checkTeamServerIdentity compares dbProjectID (metadata._project_id in the database) against expectedProjectID (local metadata.json) and they differ during verifyTeamServerSchema.

Common situations: --database/--db override pointing at another project's database; dolt_database repointed in config after 'bd init'; operator re-provisioned the database for a different project; cloning a repo without regenerating local metadata against the right database.

Related errors

• uow: database %q not found — the schema is managed by beads-
• database %q not found on Dolt server at %s:%d
• failed to open database: %w Hint: %s
• loading status configuration: %w
• database not available: %w

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