server started (PID %d) but not accepting connections on por

Error message

server started (PID %d) but not accepting connections on port %d: %w

%s

What it means

This error is returned by doltserver.Start when the dolt sql-server process spawned successfully (its PID is alive) but waitForReady never observed a MySQL handshake on the bound port within the ready timeout. Before returning, Start kills the process and removes the PID/port files; if the server log contains journal-corruption errors, the generic message is upgraded to include corruptJournalRecoveryHint with recovery steps.

Source

Thrown at internal/doltserver/doltserver.go:1503

		return nil, fmt.Errorf("writing PID file: %w", err)
	}
	if err := writePortFile(beadsDir, actualPort); err != nil {
		if proc, findErr := os.FindProcess(pid); findErr == nil {
			_ = proc.Kill()
		}
		_ = os.Remove(pidPath(beadsDir))
		return nil, fmt.Errorf("writing port file: %w", err)
	}

	// Wait for server to accept connections
	if err := waitForReady(cfg.Host, actualPort, readyTimeout()); err != nil {
		if proc, findErr := os.FindProcess(pid); findErr == nil {
			_ = proc.Kill()
		}
		_ = os.Remove(pidPath(beadsDir))
		_ = os.Remove(portPath(beadsDir))
		if hasJournalCorruption, logErr := logHasCorruptJournalError(logPath(beadsDir)); logErr == nil && hasJournalCorruption {
			return nil, fmt.Errorf("server started (PID %d) but not accepting connections on port %d: %w\n\n%s",
				pid, actualPort, err, corruptJournalRecoveryHint(beadsDir))
		}
		return nil, fmt.Errorf("server started (PID %d) but not accepting connections on port %d: %w\nCheck logs: %s",
			pid, actualPort, err, logPath(beadsDir))
	}

	return &State{
		Running: true,
		PID:     pid,
		Port:    actualPort,
		DataDir: doltDir,
	}, nil
}

// EnsureGlobalDatabase connects to the shared Dolt server and creates the
// beads_global database if it doesn't already exist. This is idempotent and
// safe to call on every shared server init. Schema initialization and config
// seeding (issue prefix, project ID) are handled by the store layer when the

View on GitHub (pinned to 71377f2769)

Solutions

Read the server log at the path printed in the error (bd dolt logs / .beads/dolt-server.log) for the underlying startup error
If the message includes the journal-corruption hint, follow it: back up and reinitialize via 'bd doctor --fix' (repair is deliberately not automatic)
Check for a hung dolt process (ps aux | grep dolt sql-server) and kill it before retrying
Increase the readiness timeout (BEADS_DOLT_READY_TIMEOUT) if the database is large but healthy
Verify the container/host has enough memory, CPU, and disk I/O for Dolt startup

Example fix

// before
// error: server started (PID 12345) but not accepting connections on port 41017: timeout...
//   [journal corruption hint follows]
// after
// $ bd doctor --fix   # backs up corrupt db and reinitializes .dolt
// $ bd dolt start

Defensive patterns

Strategy: try-catch

Validate before calling

// Before Start, check for known corruption markers so you can repair proactively
if dirs, detErr := doltserver.DetectCorruptManifestIfAvailable(beadsDir); detErr == nil && len(dirs) > 0 {
    // run: bd doctor --fix  before attempting startup
    fmt.Fprintf(os.Stderr, "corrupt manifest detected in %v; run bd doctor --fix\n", dirs)
}

Try / catch

state, err := doltserver.Start(cfg)
if err != nil {
    var logHint string
    if strings.Contains(err.Error(), "journal") || strings.Contains(err.Error(), "corrupt") {
        // corruption path: run bd doctor --fix, do not blind-retry
        fmt.Fprintln(os.Stderr, "corruption suspected; run: bd doctor --fix")
        os.Exit(1)
    }
    _ = logHint
    return fmt.Errorf("dolt server start failed: %w (check %s)", err, doltserver.LogPath(beadsDir))
}

Prevention

Always stop the server with bd dolt stop (graceful) instead of SIGKILL
Enable graceful host shutdowns so the dolt process is never hard-killed
Read .beads/dolt-server.log immediately when startup is slow
Raise BEADS_DOLT_READY_TIMEOUT for large databases
Run bd doctor periodically to catch journal/manifest issues early

When it happens

Trigger: waitForReady(cfg.Host, actualPort, readyTimeout()) exhausts its deadline — the server process is running but the MySQL engine never starts accepting/greeting connections, e.g. Dolt is stuck initializing a corrupt journal, the log shows corrupt-journal errors, or the server hangs during startup (slow disk, resource starvation).

Common situations: Unclean shutdown (power loss, SIGKILL) leaving a corrupt Dolt journal; a shared multi-tenant server starved of CPU/disk; container resource limits preventing Dolt from finishing startup; very large databases taking longer than the ready timeout to open; server crashing after the initial liveness check but before listening.

Related errors

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