d2lang/d2 · error

failed to %scompile: %w

Error message

failed to %scompile: %w

What it means

When compile() fails without producing any SVG, watch wraps the error as "failed to <re>compile", preserving the underlying cause. The prefix is "compile" on first compile and "recompile" on subsequent watch triggers.

Source

Thrown at d2cli/watch.go:453

				continue
			}
			w.pw = newPW
		}

		fs := trackedFS{}
		w.boardpathMu.Lock()
		var boardPath []string
		if w.boardPath != "" {
			boardPath = strings.Split(w.boardPath, string(os.PathSeparator))
		}
		svg, _, err := compile(ctx, w.ms, w.plugins, &fs, w.layout, w.renderOpts, w.fontFamily, w.monoFontFamily, w.animateInterval, w.inputPath, w.outputPath, boardPath, false, w.bundle, w.forceAppendix, w.pw.Browser, w.outputFormat, w.asciiMode)
		w.boardpathMu.Unlock()
		errs := ""
		if err != nil {
			if len(svg) > 0 {
				err = fmt.Errorf("failed to fully %scompile (rendering partial svg): %w", recompiledPrefix, err)
			} else {
				err = fmt.Errorf("failed to %scompile: %w", recompiledPrefix, err)
			}
			errs = err.Error()
			w.ms.Log.Error.Print(errs)
		}
		err = w.replaceWatchList(ctx, fs.opened)
		if err != nil {
			return err
		}

		w.broadcast(&compileResult{
			SVG:   string(svg),
			Scale: w.renderOpts.Scale,
			Err:   errs,
		})

		if firstCompile {
			firstCompile = false
			url := fmt.Sprintf("http://%s", w.l.Addr())

View on GitHub (pinned to 0d69dca6f5)

Solutions

1. Read the wrapped cause after the colon — it identifies the exact line/key
2. Fix the syntax or semantic error in the .d2 file
3. Validate the file with a one-shot `d2 file.d2` run (no watch) to see full errors

Example fix

// before
x.style.bogus: 3
// after
x.style.border-radius: 3

// validate before watching:
// d2 file.d2 /tmp/out.svg   # surfaces parse/semantic errors immediately

if strings.Contains(errStr, "failed to compile") {
	cause := strings.SplitN(errStr, ": ", 2)
	// cause[1] holds the precise line/key error
}

When it happens

Trigger: compileLoop calls compile() and it returns err with an empty svg — e.g. parse errors, invalid style values, layout errors, or missing resources in the .d2 input.

Common situations: Editing a .d2 file in watch mode and introducing a syntax error, using an invalid style key/value, or a plugin/layout failure.

Related errors

• response.error.message
• failed to fully %scompile (rendering partial svg): %w
• response.error.message
• response.error.message
• failed to fully compile (partial render written) %s: %w

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