GopeedLab/gopeed · error

webview page handle is not initialized

Error message

webview page handle is not initialized

What it means

PageHandle.page() is the internal accessor used by cookie/navigation-facing methods (GetCookies, SetCookie, DeleteCookie, ClearCookies). It fails when the handle is nil or its runtime reference is nil — i.e. a zero-value PageHandle or one not produced by a successful Runtime open. Execute-based methods (URL, Content, Evaluate) do not go through this check.

Source

Thrown at pkg/download/engine/webview/runtime.go:426

func (p *PageHandle) Content() (string, error) {
	value, err := p.Execute(`() => document.documentElement ? document.documentElement.outerHTML : ""`)
	if err != nil {
		return "", err
	}
	return parseString(value), nil
}

func (p *PageHandle) Close() error {
	if p == nil || p.runtime == nil {
		return nil
	}
	return p.runtime.closePage(p.id)
}

func (p *PageHandle) page() (Page, error) {
	if p == nil || p.runtime == nil {
		return nil, fmt.Errorf("webview page handle is not initialized")
	}
	return p.runtime.getPage(p.id)
}

func (p *PageHandle) poll(opts WaitOptions, fn func() (any, bool, error)) (any, bool, error) {
	timeout := time.Duration(defaultWaitTimeoutMS(opts.TimeoutMS)) * time.Millisecond
	pollInterval := time.Duration(defaultPollIntervalMS(opts.PollIntervalMS)) * time.Millisecond
	deadline := time.Now().Add(timeout)
	for {
		value, matched, err := fn()
		if err != nil {
			return nil, false, err
		}
		if matched {
			return value, true, nil
		}
		if time.Now().After(deadline) {
			return nil, false, nil

View on GitHub (pinned to 7b7327ffb3)

Solutions

1. Always obtain the PageHandle from a successful runtime Open/NewPage call and check that call's error first
2. Nil-check the handle before calling cookie-related methods
3. Pass *PageHandle by pointer and never construct it manually

Example fix

// before
var page PageHandle;
await page.getCookies(); // -> webview page handle is not initialized
// after
const [page, err] = await runtime.open(url);
if (err) throw err;
const cookies = await page.getCookies();

if page == nil {
    return errors.New("open a page before calling cookie APIs")
}

// Go: PageHandle is ready only when obtained from a successful open
func pageReady(p *webview.PageHandle) bool {
    return p != nil // runtime is unexported; a non-nil handle from Open is always initialized
}

When it happens

Trigger: Declaring var p webview.PageHandle (or page := &webview.PageHandle{}) and calling p.GetCookies(); storing a handle in a struct field that was never assigned from Open's return value; ignoring Open's error and using the nil/zero handle it returned.

Common situations: Optional page fields in helper structs that stay nil on early-exit paths; copying PageHandle values instead of pointers during refactors; tests constructing handles directly.

Related errors

• page not found
• unexpected waitForFunction payload: %T
• invalid waitUntil: %s
• execute expects a string or function
• NAVIGATION_FAILED

AI-assisted analysis of GopeedLab/gopeed@7b7327ffb3 (2026-08-16). Data as JSON: /api/errors/32611e13996789fc. Report an issue: GitHub.