gastownhall/beads · error

server started (PID ) but not accepting connections on port…

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.

Solutions

1. Inspect the log file named in the error (.beads/dolt-server.log or bd dolt logs) for the actual startup failure
2. Run the dolt binary manually (`dolt sql-server --config ...`) in the data dir to see the crash/error directly
3. Check dolt is on a compatible, working version (`dolt version`; upgrade or reinstall)
4. Confirm cfg.Host is reachable (default 127.0.0.1) and no firewall blocks the port; retry with an explicit free port
5. 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

// 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()

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
}

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

• server started (PID ) but not accepting connections on port
• dolt sql-server exited before listener became ready
• timeout after waiting for server at
• a conflict was not cleared (no conflict row deleted)
• acquire connection for compact

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

Appendix: 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)