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

Error message

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

What it means

This is the non-corruption variant of the same Start readiness failure: the dolt sql-server process spawned (PID alive) but never accepted connections on its port within readyTimeout(), and the log scan found no corrupt-journal errors. Start kills the process, removes the PID and port state files, and returns this error pointing the operator at the server log for the real cause.

Source

Thrown at internal/doltserver/doltserver.go:1506

		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
// global database is first opened with CreateIfMissing=true.
//
// Returns nil if the database already exists or was successfully created.

View on GitHub (pinned to 71377f2769)

Solutions

Inspect the log file named in the error (.beads/dolt-server.log or bd dolt logs) for the actual startup failure
Run the dolt binary manually (`dolt sql-server --config ...`) in the data dir to see the crash/error directly
Check dolt is on a compatible, working version (`dolt version`; upgrade or reinstall)
Confirm cfg.Host is reachable (default 127.0.0.1) and no firewall blocks the port; retry with an explicit free port
Raise the ready timeout if startup is merely slow (large DB, slow disk) and retry

Example fix

// before
// error: server started (PID 12345) but not accepting connections on port 41017: timeout after 15s waiting for server at 127.0.0.1:41017
//   Check logs: /repo/.beads/dolt-server.log
// after: diagnose via the log, then e.g.
// $ tail -50 /repo/.beads/dolt-server.log   # shows real cause (crash, bind error)
// $ dolt version && dolt config list       # verify healthy dolt install
// $ bd dolt start                          # retry

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: verify the dolt binary works and the host is bindable
if out, err := exec.Command("dolt", "version").Output(); err != nil {
    return fmt.Errorf("dolt binary broken: %w", err)
}
ln, lerr := net.Listen("tcp", net.JoinHostPort(cfg.Host, "0"))
if lerr != nil {
    return fmt.Errorf("host %s not bindable: %w", cfg.Host, lerr)
}
ln.Close()

Try / catch

state, err := doltserver.Start(cfg)
if err != nil {
    if strings.Contains(err.Error(), "not accepting connections") {
        log := doltserver.LogPath(beadsDir)
        if data, rerr := os.ReadFile(log); rerr == nil {
            return fmt.Errorf("start failed; server log tail: %s", tail(string(data), 40))
        }
    }
    return err
}

Prevention

Keep the dolt binary up to date and compatible with the data directory
Pin cfg.Host to a valid local interface (127.0.0.1) unless remote access is required
Ensure SELinux/firewall permits loopback connections
Use bd dolt restart instead of concurrent stop/start from multiple processes
Increase the ready timeout on slow storage or very large databases

When it happens

Trigger: waitForReady times out with a healthy-looking journal: the server binds late or never — e.g. dolt binary crash after the 200ms liveness check (use `dolt sql-server` failing on config), port firewall/loopback issues, wrong host binding (cfg.Host mismatch), or startup slower than the ready timeout.

Common situations: dolt version incompatible with the data directory causing a crash mid-init; server bound to a different interface than cfg.Host; SELinux/firewall blocking loopback; resource-limited containers; first-start on a huge dataset exceeding the readiness window; broken dolt install missing required shared libraries.

Related errors

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