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 project ID:               %s

This means the Dolt server is serving a DIFFERENT project's database.
This can happen when:
  - Another project's server is running on the same port
  - The server restarted with a different data directory

To diagnose: bd dolt status
Do NOT run 'bd init' — your data likely exists, just on a different server.

What it means

This is a safety guard against connecting to a database belonging to a different project. The store compares the local metadata.json project ID with the database's stored project ID and refuses the connection on mismatch, preventing cross-project data corruption. It includes diagnostic guidance instead of a plain error.

Source

Thrown at internal/storage/dolt/store.go:2124

	// Load local project ID from metadata.json
	metaCfg, err := configfile.Load(beadsDir)
	if err != nil || metaCfg == nil {
		return nil // no local config — skip verification
	}
	localID := metaCfg.ProjectID
	if localID == "" {
		return nil // old-style metadata.json without project_id — skip
	}

	// Read project ID from database metadata table
	dbID, err := s.GetMetadata(ctx, "_project_id")
	if err != nil || dbID == "" {
		return nil // old database without project_id — skip
	}

	if localID != dbID {
		return fmt.Errorf(
			"PROJECT IDENTITY MISMATCH — refusing to connect\n\n"+
				"  Local project ID (metadata.json):  %s\n"+
				"  Database project ID:               %s\n\n"+
				"This means the Dolt server is serving a DIFFERENT project's database.\n"+
				"This can happen when:\n"+
				"  - Another project's server is running on the same port\n"+
				"  - The server restarted with a different data directory\n\n"+
				"To diagnose: bd dolt status\n"+
				"Do NOT run 'bd init' — your data likely exists, just on a different server.",
			localID, dbID)
	}
	return nil
}

func (s *DoltStore) verifyGlobalProjectIdentity(ctx context.Context, beadsDir string) error {
	if beadsDir == "" {
		return nil
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run bd dolt status to identify which project the server is actually serving
2. Stop the wrong server and start the correct project's server on that port
3. Verify the server's data directory matches this project (.beads)
4. Do NOT run bd init — the data likely exists on another server

Example fix

// before (wrong project's server on port)
bd dolt start-server  # uses wrong data dir
// after
bd dolt status  # confirm serving project
bd dolt start-server --data-dir /path/to/this/project/.beads

localID := readProjectIDFromMetadata(".beads/metadata.json")
dbID, err := store.GetMetadata(ctx, "_project_id")
if err == nil && dbID != "" && dbID != localID {
    return fmt.Errorf("project mismatch: local=%s db=%s", localID, dbID)
}

if err != nil {
    if strings.Contains(err.Error(), "PROJECT IDENTITY MISMATCH") {
        // run bd dolt status; fix server/port before retrying
    }
    return err
}

When it happens

Trigger: Calling any open/connect path that runs verifyProjectIdentity where s.GetMetadata(ctx, "_project_id") returns a non-empty ID different from the local metadata.json project ID.

Common situations: Another project's Dolt server is running on the same port; the Dolt server restarted pointing at a different data directory; two projects share a port by mistake.

Related errors

• GLOBAL PROJECT IDENTITY MISMATCH — refusing to connect Ex
• multiple .doltcfg directories detected
• dolt directory is required
• identity: invalid proxy secret
• ErrFSCKTimeout

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