d2lang/d2 · error

render target "%s" not found

Error message

render target "%s" not found

What it means

compile() resolves the board to render via rootDiagram.GetBoard(boardPath). When no board matches the dotted path given by --board, diagram is nil and compile returns 'render target "<path>" not found'.

Source

Thrown at d2cli/main.go:560

		fmt.Print(string(jsonOutput))
		os.Exit(42)
		return nil, false, nil
	}

	cancel := background.Repeat(func() {
		ms.Log.Info.Printf("compiling & running layout algorithms...")
	}, time.Second*5)
	defer cancel()

	rootDiagram, g, err := d2lib.Compile(ctx, string(input), opts, &renderOpts)
	if err != nil {
		return nil, false, err
	}
	cancel()

	diagram := rootDiagram.GetBoard(boardPath)
	if diagram == nil {
		return nil, false, fmt.Errorf(`render target "%s" not found`, strings.Join(boardPath, "."))
	}
	if noChildren {
		diagram.Layers = nil
		diagram.Scenarios = nil
		diagram.Steps = nil
	}

	plugin, _ := d2plugin.FindPlugin(ctx, plugins, *opts.Layout)

	if animateInterval > 0 {
		masterID, err := diagram.HashID(renderOpts.Salt)
		if err != nil {
			return nil, false, err
		}
		renderOpts.MasterID = masterID
	}

	pinfo, err := plugin.Info(ctx)

View on GitHub (pinned to 0d69dca6f5)

Solutions

1. List the boards in the .d2 file and correct the --board path (join nested boards with '.')
2. Remove the --board flag to render the root board
3. Escape/rename boards whose names contain dots or special characters

Example fix

// before
d2 --board lyaers.main input.d2 out.svg
// after
d2 --board layers.main input.d2 out.svg

// pre-check board names in your .d2 source against the --board path
names := collectBoardNames(source) // layers/scenarios/steps
if !containsPath(names, strings.Split(boardFlag, ".")) {
    return fmt.Errorf("board %q does not exist", boardFlag)
}

if _, _, err := compile(...); err != nil && strings.Contains(err.Error(), "not found") {
    return fmt.Errorf("check --board path %q: %w", boardFlag, err)
}

When it happens

Trigger: Running d2 with a --board flag whose name doesn't match any layer/scenario/step in the diagram, e.g. 'd2 --board layers.foo input.d2 out.svg'.

Common situations: Typos or wrong nesting order in the board path, boards renamed after the flag was written, using dots in board names that collide with path separators.

Related errors

• %s is not a supported format. Supported formats are: %s
• failed to fully compile (partial render written) %s: %w
• failed to compile %s: %w
• multiboard output cannot be written to stdout
• expected .ttf file but %s has extension %s

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