Skip to content

rx.script(id=...) inside App(head_components=[...]) crashes compile: "You cannot use stateful components or hooks in the document root" #6979

Description

@masenf

Describe the bug

Passing id= to an rx.script used in App(head_components=[...]) crashes the compile. The id prop generates a useRef hook, which trips create_document_root's guard. The same id= on a page-level rx.script works fine, so this is a surprising asymmetry — and the error message gives no hint that the offending thing is an id prop on a script tag.

To Reproduce

import reflex as rx

def index():
    return rx.text("hello")

app = rx.App(
    head_components=[rx.script(src="/probe.js", id="head-probe")],
)
app.add_page(index)
reflex run

Observed behavior

ValueError: You cannot use stateful components or hooks in the document root. Check your head components.

Compile aborts. Workaround: drop the id= on the head_components script.

Expected behavior

Either support it (an id on a head script has no need of a ref in the document root), or raise a targeted error naming the component and prop that introduced the hook, so users can find it. "Check your head components" does not point at the id= prop, and the identical prop is legal on page-level scripts.

Specifics (please complete the following information):

  • Python Version: 3.11
  • Reflex Version: 0.9.9a1
  • OS: linux

Additional context

  • Severity: low (usability gotcha). Not a regression — same on 0.9.8.
  • Found during 0.9.9a1 pre-release testing (while exercising the rx.script head-update changes); test app on branch claude/reflex-prerelease-testing-t0sd90 under prerelease-testing/2026-08-27-v0.9.9a1/components/.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions