What causes "empty map key: %q" in d2lang/d2?

Guard the input: trim whitespace and reject empty strings before parsing

empty map key: %q

Error message

empty map key: %q

What it means

ParseMapKey returns this when the input produced no parse errors but yielded a nil map key — the string was empty or contained nothing usable as a key, so there is no AST node to return.

Source

Thrown at d2parser/parse.go:113

	}
	if k == nil {
		return nil, fmt.Errorf("empty key: %q", key)
	}
	return k, nil
}

func ParseMapKey(mapKey string) (*d2ast.Key, error) {
	p := &parser{
		reader: strings.NewReader(mapKey),
		err:    &ParseError{},
	}

	mk := p.parseMapKey()
	if !p.err.Empty() {
		return nil, fmt.Errorf("failed to parse map key %q: %w", mapKey, p.err)
	}
	if mk == nil {
		return nil, fmt.Errorf("empty map key: %q", mapKey)
	}
	return mk, nil
}

func ParseValue(value string) (d2ast.Value, error) {
	p := &parser{
		reader: strings.NewReader(value),
		err:    &ParseError{},
	}

	v := p.parseValue()
	if !p.err.Empty() {
		return nil, fmt.Errorf("failed to parse value %q: %w", value, p.err)
	}
	if v.Unbox() == nil {
		return nil, fmt.Errorf("empty value: %q", value)
	}
	return v.Unbox(), nil

View on GitHub (pinned to 0d69dca6f5)

Solutions

Guard the input: trim whitespace and reject empty strings before parsing
Check upstream generation logic for why a blank map key was produced
Skip empty fragments when iterating over lines/blocks of a .d2 file

Example fix

// before
mk, _ := d2parser.ParseMapKey(block) // block may be "\n"
// after
block = strings.TrimSpace(block)
if block == "" {
    return nil, nil // nothing to parse
}
mk, err := d2parser.ParseMapKey(block)

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(snippet) == "" {
    return nil, nil // or a explicit error, don't call ParseMapKey
}
mk, err := d2parser.ParseMapKey(snippet)

Try / catch

mk, err := d2parser.ParseMapKey(snippet)
if err != nil {
    if strings.HasPrefix(err.Error(), "empty map key") {
        return nil, nil // skip empty fragment
    }
    return err
}

Prevention

Trim whitespace/newlines before parsing map-key fragments
Filter out blank lines/blocks when processing .d2 content
Verify template variables interpolate before parsing output
Return early on empty sections instead of deferring to the parser

When it happens

Trigger: Calling d2parser.ParseMapKey("") or with a string of only whitespace/newlines such that parseMapKey returns nil.

Common situations: Empty section of a generated board file being fed back for editing; string slicing producing blank lines; a template variable that didn't interpolate.

Related errors

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