What causes "native ELK layout failed: %w" in d2lang/d2?

Inspect the wrapped cause with errors.Is/As on the returned error to see the native failure

native ELK layout failed: %w

Error message

native ELK layout failed: %w

What it means

The native ELK layout engine ran elk.LayoutJSON to compute graph layout and the underlying native ELK execution failed. The error wraps the original cause with %w so callers can errors.Is/As into the root failure.

Source

Thrown at d2layouts/d2elklayout/layout.go:483

		elkEdges[edge] = e
	}

	for k, ports := range ports {
		width := elkNodes[k.obj].Width
		spacing := width / float64(len(ports)+1)
		for i, p := range ports {
			p.X = float64(i+1) * spacing
		}
	}

	raw, err := json.Marshal(elkGraph)
	if err != nil {
		return err
	}

	jsonOut, err := elk.LayoutJSON(raw)
	if err != nil {
		return fmt.Errorf("native ELK layout failed: %w", err)
	}

	err = json.Unmarshal(jsonOut, &elkGraph)
	if err != nil {
		return err
	}

	byID := make(map[string]*d2graph.Object)
	walk(g.Root, nil, func(obj, parent *d2graph.Object) {
		n := elkNodes[obj]

		parentX := 0.0
		parentY := 0.0
		if parent != nil && parent != g.Root {
			parentX = parent.TopLeft.X
			parentY = parent.TopLeft.Y
		}
		obj.TopLeft = geo.NewPoint(parentX+n.X, parentY+n.Y)

View on GitHub (pinned to 0d69dca6f5)

Solutions

Inspect the wrapped cause with errors.Is/As on the returned error to see the native failure
Verify the ELK native runtime/JVM is installed and reachable in your environment
Switch to another layout engine (e.g. dagre) via the layout option to isolate ELK-specific issues
Reduce graph size/complexity if ELK fails on resource limits

Example fix

// before
err := graph.Layout(ctx, "elk")
// after
if err := graph.Layout(ctx, "elk"); err != nil {
	log.Printf("elk failed, falling back: %v", err)
	err = graph.Layout(ctx, "dagre")
}

Defensive patterns

Strategy: fallback

Validate before calling

if layoutName == "elk" {
	if _, err := exec.LookPath("java"); err != nil { layoutName = "dagre" }
}

Try / catch

if err := graph.Layout(ctx, "elk"); err != nil {
	var nativeErr *exec.ExitError
	if errors.As(err, &nativeErr) {
		return errors.Join(ErrELKRuntime, err)
	}
	return err
}

Prevention

Ensure the native ELK/JVM runtime is installed in deployment images
Wrap Layout errors with errors.Is/As to surface the wrapped root cause
Benchmark alternative engines (dagre) so a fallback is ready
Monitor memory limits; ELK can OOM on very large graphs

When it happens

Trigger: Calling Layout (directly or via DefaultLayout) when the embedded native ELK binary fails to lay out the graph JSON — e.g. the ELK process errors, panics, or the JVM/native runtime is unavailable.

Common situations: Missing or corrupted native ELK/JVM dependency on the host; unsupported graph constructs passed to ELK; resource exhaustion (OOM) in the layout process; restricted environments (containers) lacking the runtime.

Related errors

AI-assisted analysis of d2lang/d2@0d69dca6f5 (2026-08-31). Data as JSON: /api/errors/872091d5f03414ea. Report an issue: GitHub.