gastownhall/beads · error

writing HTML output: %w

Error message

writing HTML output: %w

What it means

The formatted Fprintf of the HTML template (title, nodes JSON, edges JSON) to the output writer failed. The marshal step succeeded; the actual write to stdout/file errored — typically broken pipe, full disk, or closed writer.

Source

Thrown at cmd/bd/graph_export.go:180

	nodes := buildHTMLGraphData(layout, subgraph)
	edges := buildHTMLEdgeData(layout, subgraph)

	nodesJSON, err := json.Marshal(nodes)
	if err != nil {
		return fmt.Errorf("marshaling HTML graph nodes: %w", err)
	}
	edgesJSON, err := json.Marshal(edges)
	if err != nil {
		return fmt.Errorf("marshaling HTML graph edges: %w", err)
	}

	title := "Beads Dependency Graph"
	if subgraph.Root != nil {
		title = fmt.Sprintf("Beads: %s (%s)", subgraph.Root.Title, subgraph.Root.ID)
	}

	if _, err := fmt.Fprintf(out, htmlTemplate, html.EscapeString(title), string(nodesJSON), string(edgesJSON)); err != nil {
		return fmt.Errorf("writing HTML output: %w", err)
	}
	return nil
}

// HTMLNode is the JSON structure for a node in the HTML visualization
type HTMLNode struct {
	ID       string `json:"id"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	Priority int    `json:"priority"`
	Type     string `json:"type"`
	Layer    int    `json:"layer"`
	Assignee string `json:"assignee,omitempty"`
}

// HTMLEdge is the JSON structure for an edge in the HTML visualization
type HTMLEdge struct {
	Source string `json:"source"`

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the wrapped io error (EPIPE vs ENOSPC vs permission)
2. Free disk space or redirect to a writable target
3. Don't close the consuming pipe prematurely

Example fix

// before
bd graph --format html | head -1
// after
bd graph --format html > graph.html

if err := bd.Graph(ctx, "html"); err != nil {
  if strings.Contains(err.Error(), "writing HTML output") {
    // check underlying cause
    log.Printf("html write failed: %v", err)
    // fall back to writing to a temp file
  }
  return err
}

When it happens

Trigger: bd graph --format html piped into a command that exits early (head), redirecting to a full filesystem, or writing to an already-closed writer in tests/embedded use.

Common situations: CI piping HTML output into head; disk quota exceeded; tests passing a closed buffer.

Related errors

• writing %s output: %w
• failed to read backup state: %w
• failed to write temp file: %w
• failed to sync temp file: %w
• failed to write issue %s: %w

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