d2lang/d2 · error

"%s" not found

Error message

"%s" not found

What it means

getBoardMap looks up the requested file path in the provided virtual filesystem map of file contents before parsing. If the path is absent from fs, there is nothing to parse and it returns this error naming the missing path.

Source

Thrown at d2lsp/d2lsp.go:69

			}
			if edge.ImportAST() != nil {
				importRanges = append(importRanges, edge.ImportAST().GetRange())
			}
		}
	} else {
		for _, ref := range f.References {
			ranges = append(ranges, ref.AST().GetRange())
		}
		if f.ImportAST() != nil {
			importRanges = append(importRanges, f.ImportAST().GetRange())
		}
	}
	return ranges, importRanges, nil
}

func getBoardMap(path string, fs map[string]string, boardPath []string) (*d2ir.Map, error) {
	if _, ok := fs[path]; !ok {
		return nil, fmt.Errorf(`"%s" not found`, path)
	}
	r := strings.NewReader(fs[path])
	ast, err := d2parser.Parse(path, r, nil)
	if err != nil {
		return nil, err
	}

	mfs, err := memfs.New(fs)
	if err != nil {
		return nil, err
	}

	m, _, err := d2ir.Compile(ast, &d2ir.CompileOptions{
		FS: mfs,
	})
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 0d69dca6f5)

Solutions

1. Add the file's content to the fs map under the exact path passed to GetRefRanges
2. Normalize paths (same separators/casing) used both as map keys and arguments
3. Ensure the path is the canonical document URI/path your tooling registered

Example fix

// before
fs := map[string]string{} // path never added
ranges, _, err := d2lsp.GetRefRanges(key, fs, nil, m)
// after
fs := map[string]string{path: docContent}
ranges, _, err := d2lsp.GetRefRanges(key, fs, nil, m)

if _, ok := fs[path]; !ok {
	return fmt.Errorf("document %q not loaded", path)
}

func fileLoaded(fs map[string]string, path string) bool {
	_, ok := fs[path]
	return ok
}

ranges, _, err := d2lsp.GetRefRanges(key, fs, boardPath, m)
if err != nil && strings.Contains(err.Error(), "not found") {
	return fmt.Errorf("ensure file %q is open in the workspace", path)
}

When it happens

Trigger: Calling d2lsp.GetRefRanges (which calls getBoardMap) with a fs map that lacks an entry for the given path — wrong path key, file never added to the map, or path separator/casing mismatch.

Common situations: LSP servers opening a file whose content wasn't loaded into the in-memory map; relative vs absolute path mismatches; stale maps after file renames or deletes.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• "%s" is invalid
• board "%v" not found
• expected "shadow" to be true or false
• expected "3d" to be true or false
• expected "multiple" to be true or false

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