alibaba/page-agent · error · Error

DOM tree not indexed yet. Can not perform actions on element

Error message

DOM tree not indexed yet. Can not perform actions on elements.

What it means

PageController throws this error when an index-based action (clickElement, inputText, selectOption, scroll, scrollHorizontally) is called before updateTree() has built and indexed the DOM tree. Elements are addressed by numeric indexes produced by the indexing pass, so without it there is no selector map to resolve indexes against. It is a guard against operating on a stale or nonexistent snapshot.

Source

Thrown at packages/page-controller/src/PageController.ts:237

	}

	/**
	 * Clean up all element highlights
	 */
	async cleanUpHighlights(): Promise<void> {
		console.log('[PageController] cleanUpHighlights')
		dom.cleanUpHighlights()
	}

	// ======= Element Actions =======

	/**
	 * Ensure the tree has been indexed before any index-based operation.
	 * Throws if updateTree() hasn't been called yet.
	 */
	private assertIndexed(): void {
		if (!this.isIndexed) {
			throw new Error('DOM tree not indexed yet. Can not perform actions on elements.')
		}
	}

	/**
	 * Click element by index
	 */
	async clickElement(index: number): Promise<ActionResult> {
		try {
			this.assertIndexed()
			const element = getElementByIndex(this.selectorMap, index)
			const elemText = this.elementTextMap.get(index)
			await clickElement(element)

			// Handle links that open in new tabs
			if (isAnchorElement(element) && element.target === '_blank') {
				return {
					success: true,
					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opened in a new tab.`,

View on GitHub (pinned to d02db1ee7c)

Solutions

1. Await pageController.updateTree() once (and after DOM changes) before any index-based action: await pageController.updateTree(); await pageController.clickElement(5)
2. Re-index between steps in an agent loop (the DOM changes after clicks/inputs)
3. Check pageController.isIndexed before acting if state is uncertain
4. Pass valid indexes obtained from getSimplifiedHTML()/getPageInfo() of the same snapshot

Example fix

// before
await controller.clickElement(3) // throws: tree not indexed

// after
await controller.updateTree()
await controller.clickElement(3)

if (!await controller.isIndexed) { await controller.updateTree() } // then call the action

try { await controller.clickElement(i) } catch (e) { if (e instanceof Error && e.message.includes('not indexed')) { await controller.updateTree(); await controller.clickElement(i) } else throw e }

When it happens

Trigger: Calling pageController.clickElement(5), inputText, selectOption, scroll, or scrollHorizontally before ever awaiting updateTree(); or after the tree was invalidated/re-indexed asynchronously while an action is already in flight.

Common situations: Running actions immediately after constructing PageController; forgetting that updateTree() is async and not awaiting it; a PageAgent loop that skips the initial observation step; calling scroll() first because it seems index-free but still goes through assertIndexed.

Related errors

• No interactive element found at index ${index}
• Element at index ${index} does not have a reference
• Element at index ${index} is not an HTMLElement
• Element is not an input, textarea, or contenteditable
• Element is not a select element

AI-assisted analysis of alibaba/page-agent@d02db1ee7c (2026-08-28). Data as JSON: /api/errors/bf5a90d96d660b77. Report an issue: GitHub.