gastownhall/beads · error

rendering managed sql-server config: %w

Error message

rendering managed sql-server config: %w

What it means

When archive-level config is used, Start() renders the managed dolt sql-server YAML via buildDoltServerYAMLConfig(host, port, debug, cfgDir). Any error from that renderer (e.g. absolutizing or validating paths inside cfgDir) is wrapped as 'rendering managed sql-server config'. With a non-explicit port the loop retries; with an explicit port it breaks and fails with lastErr.

Source

Thrown at internal/doltserver/doltserver.go:1393

		if !explicitPort {
			attempts = maxEphemeralPortAttempts
		}

		for i := range attempts {
			if !explicitPort {
				p, allocErr := allocateEphemeralPort(cfg.Host)
				if allocErr != nil {
					lastErr = allocErr
					continue
				}
				actualPort = p
			}

			var cmdArgs []string
			if useArchiveLevelConfig {
				cfgBody, cfgErr := buildDoltServerYAMLConfig(cfg.Host, actualPort, debug, cfgDir)
				if cfgErr != nil {
					lastErr = fmt.Errorf("rendering managed sql-server config: %w", cfgErr)
					if !explicitPort {
						continue
					}
					break
				}
				// filepath.Abs defensively: the child's cwd is doltDir (cmd.Dir
				// below), so a relative configPath would resolve against the
				// wrong directory (matches the sibling dbproxy/server path,
				// which abs's its configPath in NewDoltServer).
				absConfigPath, absErr := filepath.Abs(doltServerConfigPath(beadsDir))
				if absErr != nil {
					lastErr = fmt.Errorf("resolving managed sql-server config path: %w", absErr)
					if !explicitPort {
						continue
					}
					break
				}
				if werr := os.WriteFile(absConfigPath, cfgBody, 0600); werr != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the beads data dir and .doltcfg directory exist and contain valid, absolute paths.
2. Avoid symlinks or relative paths in the configured beadsDir; use an absolute path.
3. Re-run after fixing permissions so resolveCfgDir produces a valid cfgDir.
4. If failure persists with an explicit port, switch to port 0 (ephemeral) to let the retry loop pick a fresh allocation.

Example fix

// before
BD_DIR=~/beads  # resolves via symlink to a moved volume
// after
BD_DIR=/absolute/stable/path/beads

const cfgDir = path.join(dataDir, '.doltcfg');
await fs.access(cfgDir, fs.constants.W_OK);
if (!path.isAbsolute(dataDir)) console.warn('use an absolute beadsDir');

null

try {
  await bdStart();
} catch (e) {
  if (/rendering managed sql-server config/.test(e.message)) {
    // retry once with ephemeral port (port 0) to let the loop reallocate
  }
  throw e;
}

When it happens

Trigger: useArchiveLevelConfig is true and buildDoltServerYAMLConfig fails, typically because paths derived from cfgDir/doltDir cannot be resolved (bad cfgDir from error 1620's resolver passing, but paths later failing).

Common situations: Relative or symlinked beadsDir producing unresolvable config paths; cfgDir removed between resolve and render (race); unusual characters in data-dir path breaking config rendering.

Related errors

• persist sync.remote to config.yaml: %w
• failed to persist sync.remote to config.yaml: %w
• failed to persist sync.remote to config.yaml: %v
• failed to configure hydration: %w
• load %s: %w; no storage database was opened or modified (sto

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