gastownhall/beads · error

ensureProxiedServerConfig: render YAML: %w

Error message

ensureProxiedServerConfig: render YAML: %w

What it means

After picking a port, ensureProxiedServerConfig renders the proxied-server YAML via renderProxiedServerConfig(port); any error from rendering is wrapped here. Since the input is a just-allocated int port, this almost always indicates a template execution failure or marshaling problem inside the renderer rather than bad user input.

Source

Thrown at cmd/bd/proxied_server.go:155

	if err := os.MkdirAll(root, config.BeadsDirPerm); err != nil {
		return "", fmt.Errorf("ensureProxiedServerConfig: mkdir %s: %w", root, err)
	}

	switch _, err := os.Stat(path); {
	case err == nil:
		return path, nil
	case !os.IsNotExist(err):
		return "", fmt.Errorf("ensureProxiedServerConfig: stat %s: %w", path, err)
	}

	port, err := proxy.PickFreePort()
	if err != nil {
		return "", fmt.Errorf("ensureProxiedServerConfig: pick free port: %w", err)
	}

	body, err := renderProxiedServerConfig(port)
	if err != nil {
		return "", fmt.Errorf("ensureProxiedServerConfig: render YAML: %w", err)
	}
	if err := atomicWriteFile(resolveConfigWriteTarget(path), body); err != nil {
		return "", fmt.Errorf("ensureProxiedServerConfig: write %s: %w", path, err)
	}
	return path, nil
}

// resolveConfigWriteTarget resolves path to its physical location before
// an atomic rewrite. os.Rename's destination argument does not follow
// symlinks — it unlinks and replaces whatever is AT that path, symlink or
// not — so writing straight to a symlinked config.yaml would silently
// replace the symlink itself with a regular file instead of updating the
// file it points at. Falls back to path unresolved when it does not exist
// yet (filepath.EvalSymlinks errors on a missing path), which covers both
// the ordinary "no config.yaml yet" case and a dangling symlink.
func resolveConfigWriteTarget(path string) string {
	resolved, err := filepath.EvalSymlinks(path)
	if err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

  1. Run `bd --version` / `bd doctor` and reinstall or upgrade bd to a clean, complete build (e.g. `go install ...@latest` or re-download the release) — a corrupted binary is the most common cause.
  2. Check bd's issue tracker for known bugs in renderProxiedServerConfig matching your version; downgrade to the previous working release if a regression was shipped.
  3. Delete any partially written config at the target path and let bd regenerate it from scratch (`rm <config-path>` then rerun).
  4. If you build from source, verify embedded template assets are intact (clean checkout, `make` per README) rather than a dirty build.
  5. File a bug with the full wrapped error if a stock binary reproduces it — template failures are usually internal defects.

Example fix

// before
$ bd serve   # bd built from dirty tree, embedded template missing
ensureProxiedServerConfig: render YAML: template: config: line 3: function "beadsDir" not defined
// after
$ make clean && make && ./bd serve   # or install an official release
Defensive patterns

Strategy: try-catch

Try / catch

path, err := ensureProxiedServerConfig(cfgPath)
if err != nil {
	var perr error
	if errors.As(err, &perr) && strings.Contains(err.Error(), "render YAML") {
		// template/render failure: reinstall or downgrade bd, then retry
		log.Fatalf("config render failed (%v); reinstall bd and retry", err)
	}
	return err
}

Prevention

When it happens

Trigger: renderProxiedServerConfig(port) returns an error: the embedded config template fails to execute (template parse/execute bug, missing template function), text/template or yaml.Marshal fails on generated values, or a version skew leaves the template registry uninitialized.

Common situations: Corrupted or partially upgraded bd binary (embedded template assets missing/mismatched); a bd build with stripped/modified embedded resources; a bug in a newer template referencing an unknown field.

Related errors

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