What causes "%v not found" in d2lang/d2?

Confirm the exact object exists (e.g. via d2oracle.GetObj or by searching the D2 script) and use its AbsID().

%v not found

Error message

%v not found

What it means

After the board is resolved, GetChildrenIDs parses absID into a map key and looks it up with g.Root.HasChild. If no object with that absolute ID exists under the board root, it returns "%v not found" with the raw absID. This means the object ID you asked about is not a node on the resolved board.

Source

Thrown at d2oracle/get.go:99

		}
	}

	return false
}

func GetChildrenIDs(g *d2graph.Graph, boardPath []string, absID string) (ids []string, _ error) {
	g = GetBoardGraph(g, boardPath)
	if g == nil {
		return nil, fmt.Errorf("board at path %v not found", boardPath)
	}

	mk, err := d2parser.ParseMapKey(absID)
	if err != nil {
		return nil, err
	}
	obj, ok := g.Root.HasChild(d2graph.Key(mk.Key))
	if !ok {
		return nil, fmt.Errorf("%v not found", absID)
	}

	for _, ch := range obj.ChildrenArray {
		ids = append(ids, ch.AbsID())
	}

	return ids, nil
}

func GetParentID(g *d2graph.Graph, boardPath []string, absID string) (string, error) {
	g = GetBoardGraph(g, boardPath)
	if g == nil {
		return "", fmt.Errorf("board at path %v not found", boardPath)
	}

	mk, err := d2parser.ParseMapKey(absID)
	if err != nil {
		return "", err

View on GitHub (pinned to 0d69dca6f5)

Solutions

Confirm the exact object exists (e.g. via d2oracle.GetObj or by searching the D2 script) and use its AbsID().
Check you are querying on the correct boardPath — the object may live on another board.
Rebuild the absID with the proper root prefix and key path (IDs are key paths like "root.a.b").
If the object was deleted, guard for its absence instead of assuming it exists.

Example fix

// before
ids, err := d2oracle.GetChildrenIDs(g, nil, "servers.db1")
// after
ids, err := d2oracle.GetChildrenIDs(g, nil, "root.servers.db1") // include root prefix

Defensive patterns

Strategy: validation

Validate before calling

if _, ok := g.Root.HasChild(d2graph.Key(mk.Key)); !ok {
	return fmt.Errorf("object %s does not exist on board %v", absID, boardPath)
}
ids, err := d2oracle.GetChildrenIDs(g, boardPath, absID)

Type guard

func objExists(g *d2graph.Graph, boardPath []string, absID string) bool {
	bg := d2oracle.GetBoardGraph(g, boardPath)
	if bg == nil {
		return false
	}
	mk, err := d2parser.ParseMapKey(absID)
	if err != nil {
		return false
	}
	_, ok := bg.Root.HasChild(d2graph.Key(mk.Key))
	return ok
}

Try / catch

ids, err := d2oracle.GetChildrenIDs(g, boardPath, absID)
if err != nil {
	if strings.Contains(err.Error(), "not found") && strings.Contains(err.Error(), absID) {
		return fmt.Errorf("object %q is gone; refresh IDs from the current graph", absID)
	}
	return err
}

Prevention

Use AbsID() values obtained from the graph, never labels or hand-built strings.
Re-fetch IDs after any edit, rename, or delete operation.
Verify the object belongs to the board you are querying.
Format IDs as root-prefixed key paths (root.a.b).

When it happens

Trigger: Calling d2oracle.GetChildrenIDs(g, boardPath, absID) with an absID such as "root.server.internal" that does not exist on that board, or an ID belonging to a different board, or a malformed key that parses but matches no object.

Common situations: Object was renamed or deleted; ID built without the root prefix or with the wrong separator; querying children of an object on board A using an ID from board B; using a rendered label instead of the actual key as the ID.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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