> ## Documentation Index
> Fetch the complete documentation index at: https://qawolf-flows-tab-consolidation-outlining.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POM Troubleshooting

> Troubleshoot common issues when using @qawolf/pom, including unregistered pages, duplicate registrations, and stale page-hook flags.

## `Unknown page: <name>` When Calling `create`

Cause: The module that calls `registerPage` for that name has not been imported,
so the registry is empty for it.

Check:

* the workspace's `register-pages` module is side-effect imported before any
  `create(name)` / `createPage(name, ...)` call
* the name passed to `create` exactly matches the name passed to `registerPage`

## `Page "<name>" is already registered.`

Cause: `registerPage` was called twice for the same name. The registry throws on
a duplicate key rather than silently overwriting.

Check:

* the name is registered in exactly one place
* two page objects are not registered under the same name

## `Cannot access '<name>' before initialization`

Cause: Two files import each other, and one of them uses the other's class while
that file is still loading — almost always a page object that `extend`s a class
declared in a file importing it back. Two page objects that import each other
are fine; extending across that pair is not, because the file that loads second
evaluates `extends` before the class exists.

Check:

* the base class lives in a file that imports neither of the two page objects
* nothing else in the cycle runs at module top level against an imported
  binding — using it inside a method body is fine, since both files have
  finished loading by then

## A Page Object's Popup Or Route Hook Never Runs

Cause: The page object is not registered, or page hooks are collected by an
own-property check on the **registered** class's prototype and the override is
inherited from a base class.

Check:

* the page object is passed to `registerPage`, even if your code only ever
  constructs it from a direct import — `installPageHooks()` walks the registry
  and cannot see an unregistered class
* `popupHandlers()` / `routeInterceptors()` is declared directly on the class
  passed to `registerPage`, not only on a base class it extends
* the entry point calls `installPageHooks()` before navigating

## `providesPageHooks: false` Contradicts The Class

Cause: A page object registered with `{ providesPageHooks: false }` declares a
`popupHandlers()` / `routeInterceptors()` override. The registry throws so the
stale flag surfaces instead of silently skipping hook installation — at
`registerPage` time for an eagerly registered class, on first load for a lazy
one.

Check:

* drop `{ providesPageHooks: false }` from that registration so its hooks are
  installed

## `this.create("X")` Is Typed As `any`

Cause: The name is not present in the `RegisteredPages` map.

Check:

* the workspace augments `RegisteredPages` (via `declare module "@qawolf/pom"`)
  with an `X: X` entry
* the augmentation module is included in the TypeScript program

## Two Registries / Pages Invisible To Each Other

Cause: More than one copy of `@qawolf/pom` resolved at runtime. The registry is
module-level state, so each copy has its own — a page registered through one is
invisible to the other.

Check:

* a single installed copy of `@qawolf/pom` resolves at runtime (no duplicate in
  a nested `node_modules`)
* workspace code does not mix `@qawolf/pom` with a locally vendored copy of the
  POM library