> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues when building a player with the React components, and how to fix them.

## "usePlayer must be used within a PlayerProvider"

A component called `usePlayer` or `usePlayerSelector` outside a
[`PlayerProvider`](/player-ui/react/player-provider). Every component must render
inside the provider. Check that it wraps your whole player UI.

## The BeyondWords player UI shows up as well as mine

The engine renders its own UI by default. Pass `showUserInterface: false` in the
provider's `args` so only your UI shows:

```tsx theme={null}
<PlayerProvider args={{ projectId: 9504, sourceId: '…', showUserInterface: false }}>
```

## A component re-renders too often (or not at all)

Read state through `usePlayerSelector` with the narrowest selector possible, not
by reading the player instance during render. The selector re-renders only when
its result changes:

```tsx theme={null}
// Re-renders only when playbackState changes
const playbackState = usePlayerSelector((p) => p.playbackState);
```

## "window is not defined" / errors during server rendering

The provider mounts the player in the browser, so it's client-only. Make sure the
component is a client component (it carries `"use client"`) and isn't executed
during server rendering. In Next.js, render it in a client component or load it
with a client-only dynamic import.

## My styles aren't being applied

The components are minimal by design, so a bare install looks plain. Add your
own classes (see [Theming](/player-ui/react/theming)), and make sure your Tailwind
config scans the directory the components were copied into so their utility
classes are generated.

## Nothing plays

* Check the `projectId` and `sourceId` (or `contentId`) are valid for your
  project.
* Browsers block audio until the user interacts with the page, so the first
  playback must come from a user action like a click.

## Seeking or changing rate does nothing during an advert

The engine intentionally blocks some actions while an advert is playing. Read
`player.advertIndex` to detect this and reflect it in your UI (for example,
disabling the progress bar) rather than assuming the action will always apply.