# Playwright Error Index

Quick-reference for specific Playwright error messages. Find your error, understand the cause, apply the fix.

> **How to use**: Search this file for the exact error text you see in your terminal or test report. Each entry gives you the cause and a working fix.

---

## Locator & Element Errors

---

### "locator.click: Target closed"

**Cause**: The page or frame navigated away (or was closed) before Playwright finished executing the action on the element.

**Common triggers**:

- Clicking a link that triggers navigation while another action is still pending
- A form submit causes a page reload before a subsequent `click()` or `fill()` resolves
- Calling `page.close()` or `context.close()` in a `finally` block that races with an in-flight action
- An unhandled exception in the application triggers an error page redirect

**Fix**: Wait for navigation to complete before performing the next action, or use `Promise.all` to coordinate the click and navigation together.

```typescript
// TypeScript — wait for navigation caused by clicking a link
await Promise.all([
  page.waitForURL("**/dashboard"),
  page.getByRole("link", { name: "Dashboard" }).click(),
])
```

```javascript
// JavaScript — same pattern
await Promise.all([
  page.waitForURL("**/dashboard"),
  page.getByRole("link", { name: "Dashboard" }).click(),
])
```

If the page is closing intentionally (e.g., a popup), capture a reference before the action:

```typescript
// TypeScript — handle popup that closes itself
const popupPromise = page.waitForEvent("popup")
await page.getByRole("button", { name: "Open popup" }).click()
const popup = await popupPromise
await popup.waitForLoadState()
// interact with popup before it closes
await popup.getByRole("button", { name: "Confirm" }).click()
```

```javascript
// JavaScript — handle popup that closes itself
const popupPromise = page.waitForEvent("popup")
await page.getByRole("button", { name: "Open popup" }).click()
const popup = await popupPromise
await popup.waitForLoadState()
await popup.getByRole("button", { name: "Confirm" }).click()
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/multi-context-and-popups.md](multi-context-and-popups.md)

---

### "waiting for locator('...') to be visible"

**Cause**: Playwright's auto-waiting timed out because the element never appeared in the DOM or remained hidden (e.g., `display: none`, `visibility: hidden`, zero size, or behind `aria-hidden`).

**Common triggers**:

- The element renders conditionally and the condition was not met (missing data, unauthenticated state)
- Content loads asynchronously and the locator was evaluated before the API response arrived
- The selector is wrong — typo in role, name, or test ID
- The element exists but is off-screen or inside a collapsed container
- CSS animation or transition keeps the element at `opacity: 0` without making it visible to Playwright

**Fix**: First confirm the locator matches what you expect using the Playwright Inspector. Then ensure the precondition for the element to appear is met.

```typescript
// TypeScript — debug: check what the locator resolves to
console.log(await page.getByRole("button", { name: "Submit" }).count())
// If 0, the element is not in the DOM — check your selector or page state

// Correct approach: wait for the data to load first
await page.waitForResponse((resp) => resp.url().includes("/api/data") && resp.status() === 200)
await expect(page.getByRole("button", { name: "Submit" })).toBeVisible()
```

```javascript
// JavaScript — same approach
console.log(await page.getByRole("button", { name: "Submit" }).count())

await page.waitForResponse((resp) => resp.url().includes("/api/data") && resp.status() === 200)
await expect(page.getByRole("button", { name: "Submit" })).toBeVisible()
```

**Related**: [core/locators.md](locators.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "locator.click: Error: strict mode violation"

**Cause**: The locator matched more than one element and Playwright's strict mode (enabled by default) refuses to act on ambiguous matches.

**Common triggers**:

- Using `getByRole('button')` when multiple buttons exist on the page
- Using `getByText('Save')` when both "Save" and "Save as draft" are present
- Partial text matching when `exact: true` is needed
- The same component is rendered multiple times (e.g., in a list)

**Fix**: Make the locator more specific so it resolves to exactly one element.

```typescript
// TypeScript

// BAD — matches multiple buttons
await page.getByRole("button", { name: "Save" }).click()

// GOOD — use exact matching
await page.getByRole("button", { name: "Save", exact: true }).click()

// GOOD — scope to a specific container
await page.getByRole("dialog").getByRole("button", { name: "Save" }).click()

// GOOD — use .first(), .last(), .nth() when order is meaningful
await page.getByRole("listitem").first().click()

// GOOD — chain with filter for list items
await page
  .getByRole("listitem")
  .filter({ hasText: "Project Alpha" })
  .getByRole("button", { name: "Delete" })
  .click()
```

```javascript
// JavaScript

// BAD — matches multiple buttons
await page.getByRole("button", { name: "Save" }).click()

// GOOD — use exact matching
await page.getByRole("button", { name: "Save", exact: true }).click()

// GOOD — scope to a specific container
await page.getByRole("dialog").getByRole("button", { name: "Save" }).click()

// GOOD — use .first(), .last(), .nth() when order is meaningful
await page.getByRole("listitem").first().click()

// GOOD — chain with filter for list items
await page
  .getByRole("listitem")
  .filter({ hasText: "Project Alpha" })
  .getByRole("button", { name: "Delete" })
  .click()
```

**Related**: [core/locators.md](locators.md), [core/locator-strategy.md](locator-strategy.md)

---

### "Error: expect(locator).toBeVisible() — locator resolved to X elements"

**Cause**: Same root cause as strict mode violation above — the assertion's locator matched multiple elements, so Playwright cannot determine which one to assert on.

**Common triggers**:

- Same as strict mode violation triggers above
- Writing `expect(page.locator('.item')).toBeVisible()` when there are many `.item` elements

**Fix**: Narrow the locator to a single element (see strict mode violation fix above). Alternatively, if you intentionally want to check all matches:

```typescript
// TypeScript — assert count instead of visibility
await expect(page.getByRole("listitem")).toHaveCount(5)

// Or assert on a specific one
await expect(page.getByRole("listitem").first()).toBeVisible()

// Or assert all are visible with a loop
for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toBeVisible()
}
```

```javascript
// JavaScript — assert count instead of visibility
await expect(page.getByRole("listitem")).toHaveCount(5)

// Or assert on a specific one
await expect(page.getByRole("listitem").first()).toBeVisible()

// Or assert all are visible with a loop
for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toBeVisible()
}
```

**Related**: [core/locators.md](locators.md), [core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "locator.fill: Error: Element is not an <input>, <textarea> or [contenteditable] element"

**Cause**: `fill()` only works on `<input>`, `<textarea>`, or elements with `contenteditable`. The locator resolved to a different element type (e.g., a `<div>`, `<label>`, or the `<form>` itself).

**Common triggers**:

- Locating by label text but the label and input are not properly associated via `for`/`id`
- Using `getByText()` instead of `getByLabel()` or `getByRole('textbox')`
- Custom components that wrap the actual `<input>` in a styled `<div>`
- Rich text editors that use `contenteditable` on an inner element, not the outer wrapper

**Fix**: Target the actual input element.

```typescript
// TypeScript

// BAD — targets the label, not the input
await page.getByText("Email").fill("user@example.com")

// GOOD — getByLabel finds the associated input
await page.getByLabel("Email").fill("user@example.com")

// GOOD — target by role
await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")

// For contenteditable rich text editors
await page.locator('[contenteditable="true"]').fill("Hello world")

// If fill() still doesn't work (e.g., custom widget), use keyboard input
await page.getByRole("textbox", { name: "Email" }).click()
await page.keyboard.type("user@example.com")
```

```javascript
// JavaScript

// BAD — targets the label, not the input
await page.getByText("Email").fill("user@example.com")

// GOOD — getByLabel finds the associated input
await page.getByLabel("Email").fill("user@example.com")

// GOOD — target by role
await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")

// For contenteditable rich text editors
await page.locator('[contenteditable="true"]').fill("Hello world")

// If fill() still doesn't work (e.g., custom widget), use keyboard input
await page.getByRole("textbox", { name: "Email" }).click()
await page.keyboard.type("user@example.com")
```

**Related**: [core/locators.md](locators.md), [core/forms-and-validation.md](forms-and-validation.md)

---

### "Error: elementHandle.click: Node is not an Element"

**Cause**: You are using the legacy ElementHandle API and the handle has gone stale — the underlying DOM node was removed or replaced by a re-render.

**Common triggers**:

- Storing an `elementHandle` in a variable and using it after a navigation or React/Vue re-render
- Using `page.$()` or `page.$$()` instead of Locator API
- Framework hydration replaces the server-rendered node with a client-rendered one

**Fix**: Switch from ElementHandle to Locator. Locators re-query the DOM on every action and never go stale.

```typescript
// TypeScript

// BAD — stale handle
const button = await page.$("button.submit")
// ... page re-renders ...
await button!.click() // Node is not an Element

// GOOD — locator always re-queries
const button = page.getByRole("button", { name: "Submit" })
// ... page re-renders ...
await button.click() // works fine
```

```javascript
// JavaScript

// BAD — stale handle
const button = await page.$("button.submit")
// ... page re-renders ...
await button.click() // Node is not an Element

// GOOD — locator always re-queries
const button = page.getByRole("button", { name: "Submit" })
// ... page re-renders ...
await button.click() // works fine
```

**Related**: [core/locators.md](locators.md)

---

### "Error: locator.click: Timeout 30000ms exceeded"

**Cause**: The element was found in the DOM but was not actionable within the timeout. "Actionable" means visible, stable (not animating), enabled, and not obscured by another element.

**Common triggers**:

- An overlay, modal, or toast is covering the element
- The element is disabled (`disabled` attribute or `aria-disabled="true"`)
- CSS animation has not completed (element is still moving)
- A loading spinner overlays the button
- The element is outside the viewport and Playwright's auto-scroll failed

**Fix**: Identify what is blocking the action using traces, then address it.

```typescript
// TypeScript

// Step 1: Enable tracing to diagnose
// In playwright.config.ts:
// use: { trace: 'on-first-retry' }
// Then run: npx playwright show-trace trace.zip

// Common fix: wait for the overlay to disappear
await expect(page.locator(".loading-overlay")).toBeHidden()
await page.getByRole("button", { name: "Submit" }).click()

// Common fix: force click when you know the overlay is benign
// (use sparingly — this skips actionability checks)
await page.getByRole("button", { name: "Submit" }).click({ force: true })

// Common fix: wait for the element to be enabled
await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled()
await page.getByRole("button", { name: "Submit" }).click()
```

```javascript
// JavaScript

// Common fix: wait for the overlay to disappear
await expect(page.locator(".loading-overlay")).toBeHidden()
await page.getByRole("button", { name: "Submit" }).click()

// Common fix: force click (use sparingly)
await page.getByRole("button", { name: "Submit" }).click({ force: true })

// Common fix: wait for the element to be enabled
await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled()
await page.getByRole("button", { name: "Submit" }).click()
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/debugging.md](debugging.md)

---

## Navigation & Page Errors

---

### "page.goto: net::ERR_CONNECTION_REFUSED"

**Cause**: Playwright could not connect to the target URL. The server is not running or is not listening on the expected host/port.

**Common triggers**:

- Forgot to start the dev server before running tests
- Dev server is on a different port than `baseURL` in config
- Server is listening on `127.0.0.1` but test uses `localhost` (or vice versa) and the OS resolves them differently
- In CI, the application build/start step failed silently
- Docker container networking: the app runs inside a container but the test tries to reach `localhost`

**Fix**: Use the `webServer` config option to let Playwright start and manage the dev server automatically.

```typescript
// TypeScript — playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000, // 2 minutes for server start
  },
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

```javascript
// JavaScript — playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

**Related**: [core/configuration.md](configuration.md), [ci/ci-github-actions.md](../ci/ci-github-actions.md)

---

### "page.goto: Timeout 30000ms exceeded"

**Cause**: The page did not reach the `load` state (by default) within the navigation timeout. The server responded but the page took too long to fully load.

**Common triggers**:

- Large assets (images, fonts, scripts) slow the page load
- Third-party scripts (analytics, ads) blocking the load event
- The page makes many API calls before becoming interactive
- The server responded with a redirect chain that takes too long

**Fix**: Use a more appropriate `waitUntil` option or increase the navigation timeout.

```typescript
// TypeScript

// Use 'domcontentloaded' instead of 'load' if you don't need all assets
await page.goto("/dashboard", { waitUntil: "domcontentloaded" })

// Or increase the navigation timeout for known slow pages
await page.goto("/dashboard", { timeout: 60_000 })

// Or set it globally in config
// playwright.config.ts
export default defineConfig({
  use: {
    navigationTimeout: 60_000,
  },
})
```

```javascript
// JavaScript

await page.goto("/dashboard", { waitUntil: "domcontentloaded" })

await page.goto("/dashboard", { timeout: 60_000 })

// playwright.config.js
module.exports = defineConfig({
  use: {
    navigationTimeout: 60_000,
  },
})
```

**Related**: [core/configuration.md](configuration.md)

---

### "Error: page.goto: Navigation failed because page was closed!"

**Cause**: The page or browser context was closed while `goto()` was still in progress. This typically happens in teardown/cleanup race conditions.

**Common triggers**:

- `afterEach` or a fixture closes the page/context before navigation completes
- Another test or hook called `browser.close()` prematurely
- A test failed and the cleanup ran while an async navigation was still pending
- Using `test.fixme()` or `test.skip()` after an async operation has started

**Fix**: Ensure cleanup only runs after all page operations complete. Use fixtures for lifecycle management instead of manual `afterEach`.

```typescript
// TypeScript

// BAD — race condition between test body and cleanup
test.afterEach(async ({ page }) => {
  await page.close() // may race with in-flight navigation
})

// GOOD — let Playwright manage page lifecycle via fixtures
// Playwright automatically creates and destroys the page per test
// No manual cleanup needed

// If you need custom cleanup, make sure to await all navigation first
test("navigates to dashboard", async ({ page }) => {
  const responsePromise = page.waitForResponse("**/api/user")
  await page.goto("/dashboard")
  await responsePromise // ensure all async ops are done
  // test assertions here
})
```

```javascript
// JavaScript — same pattern

test("navigates to dashboard", async ({ page }) => {
  const responsePromise = page.waitForResponse("**/api/user")
  await page.goto("/dashboard")
  await responsePromise
  // test assertions here
})
```

**Related**: [core/fixtures-and-hooks.md](fixtures-and-hooks.md)

---

### "page.waitForNavigation: Timeout 30000ms exceeded"

**Cause**: `waitForNavigation()` waited for a full page navigation that never happened. In SPAs, client-side routing does not trigger a navigation event.

**Common triggers**:

- Using `waitForNavigation()` with a SPA that uses React Router, Vue Router, or Next.js client-side navigation
- The navigation already happened before `waitForNavigation()` was called (race condition)
- Using the deprecated pattern when `waitForURL()` is the correct replacement

**Fix**: Replace `waitForNavigation()` with `waitForURL()` which works with both SPAs and traditional page loads.

```typescript
// TypeScript

// BAD — deprecated, race-prone, doesn't work with SPA routing
await page.waitForNavigation()

// GOOD — works with SPAs and full navigations
await page.getByRole("link", { name: "Dashboard" }).click()
await page.waitForURL("**/dashboard")

// GOOD — combine with glob patterns
await page.waitForURL(/\/dashboard\/\d+/)

// GOOD — for SPA route changes, assert on visible content
await page.getByRole("link", { name: "Settings" }).click()
await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible()
```

```javascript
// JavaScript

// BAD — deprecated, race-prone
await page.waitForNavigation()

// GOOD — works with SPAs and full navigations
await page.getByRole("link", { name: "Dashboard" }).click()
await page.waitForURL("**/dashboard")

// GOOD — combine with glob patterns
await page.waitForURL(/\/dashboard\/\d+/)

// GOOD — for SPA route changes, assert on visible content
await page.getByRole("link", { name: "Settings" }).click()
await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible()
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "Error: frame.goto: Frame was detached"

**Cause**: The iframe was removed from the DOM (detached) while Playwright was navigating or interacting with it.

**Common triggers**:

- The parent page re-rendered and recreated the iframe element
- JavaScript on the parent page removed and re-added the iframe
- A SPA route change unmounted the component containing the iframe
- An ad iframe reloaded itself

**Fix**: Re-acquire the frame reference after the parent page updates.

```typescript
// TypeScript

// BAD — frame reference becomes stale
const frame = page.frameLocator("#my-iframe")
// ... parent page re-renders ...
await frame.getByRole("button").click() // Frame was detached

// GOOD — use frameLocator (re-evaluates each time)
// frameLocator itself is lazy, but the frame it points to must exist
await expect(page.frameLocator("#my-iframe").getByRole("button")).toBeVisible()
await page.frameLocator("#my-iframe").getByRole("button").click()

// GOOD — wait for the iframe to be present after a re-render
await expect(page.locator("#my-iframe")).toBeAttached()
await page.frameLocator("#my-iframe").getByRole("button").click()
```

```javascript
// JavaScript

// GOOD — frameLocator re-evaluates lazily
await expect(page.frameLocator("#my-iframe").getByRole("button")).toBeVisible()
await page.frameLocator("#my-iframe").getByRole("button").click()

// GOOD — wait for the iframe to be present after a re-render
await expect(page.locator("#my-iframe")).toBeAttached()
await page.frameLocator("#my-iframe").getByRole("button").click()
```

**Related**: [core/iframes-and-shadow-dom.md](iframes-and-shadow-dom.md)

---

## Test Framework Errors

---

### "Error: Test timeout of 30000ms exceeded"

**Cause**: The entire test (including all hooks and assertions) did not complete within the configured test timeout.

**Common triggers**:

- Waiting for an element that never appears (wrong locator, missing data)
- Unresolved `page.waitForEvent()` — the expected event never fires
- Slow test environment (CI with limited resources)
- Too many sequential actions in a single test
- A `beforeEach` hook performs expensive setup (login, data seeding)

**Fix**: Identify the slow step using `test.step()` and traces, then either fix the root cause or adjust the timeout.

```typescript
// TypeScript

// Increase timeout for a specific slow test
test("generates large report", async ({ page }) => {
  test.setTimeout(120_000) // 2 minutes for this test only
  // ...
})

// Increase timeout globally in config
// playwright.config.ts
export default defineConfig({
  timeout: 60_000, // 60 seconds per test
})

// Better: diagnose with test.step() to find what's slow
test("checkout flow", async ({ page }) => {
  await test.step("add item to cart", async () => {
    await page.goto("/products")
    await page.getByRole("button", { name: "Add to Cart" }).click()
  })

  await test.step("complete checkout", async () => {
    await page.getByRole("link", { name: "Cart" }).click()
    await page.getByRole("button", { name: "Checkout" }).click()
  })
})
```

```javascript
// JavaScript

test("generates large report", async ({ page }) => {
  test.setTimeout(120_000)
  // ...
})

// playwright.config.js
module.exports = defineConfig({
  timeout: 60_000,
})

test("checkout flow", async ({ page }) => {
  await test.step("add item to cart", async () => {
    await page.goto("/products")
    await page.getByRole("button", { name: "Add to Cart" }).click()
  })

  await test.step("complete checkout", async () => {
    await page.getByRole("link", { name: "Cart" }).click()
    await page.getByRole("button", { name: "Checkout" }).click()
  })
})
```

**Related**: [core/configuration.md](configuration.md), [core/debugging.md](debugging.md)

---

### "Error: expect(received).toMatchSnapshot()"

**Cause**: The current screenshot or text does not match the stored baseline snapshot.

**Common triggers**:

- Legitimate UI changes that require updating the snapshot
- Different rendering between local and CI (fonts, anti-aliasing, OS-level rendering)
- Dynamic content (timestamps, random IDs, ads) that changes between runs
- Different viewport sizes or device emulation settings between environments

**Fix**: Update the snapshot if the change is intentional, or mask/hide dynamic areas.

```typescript
// TypeScript

// Update snapshots after intentional changes
// Run: npx playwright test --update-snapshots

// Mask dynamic content before taking a screenshot
await expect(page).toHaveScreenshot("dashboard.png", {
  mask: [page.locator(".timestamp"), page.locator(".random-ad")],
  maxDiffPixelRatio: 0.01, // allow 1% pixel difference
})

// Use text snapshot with a sanitizer for dynamic values
const content = await page.getByRole("main").textContent()
const sanitized = content!.replace(/\d{4}-\d{2}-\d{2}/g, "DATE")
expect(sanitized).toMatchSnapshot("dashboard-content.txt")
```

```javascript
// JavaScript

// Update snapshots: npx playwright test --update-snapshots

await expect(page).toHaveScreenshot("dashboard.png", {
  mask: [page.locator(".timestamp"), page.locator(".random-ad")],
  maxDiffPixelRatio: 0.01,
})

const content = await page.getByRole("main").textContent()
const sanitized = content.replace(/\d{4}-\d{2}-\d{2}/g, "DATE")
expect(sanitized).toMatchSnapshot("dashboard-content.txt")
```

**Related**: [core/visual-regression.md](visual-regression.md)

---

### "Error: browserType.launch: Executable doesn't exist"

**Cause**: The Playwright browser binaries are not installed on this machine or they were installed for a different Playwright version.

**Common triggers**:

- Fresh clone of a project without running the install step
- Upgrading `@playwright/test` without reinstalling browsers
- CI environment missing the install step
- Using `npm ci` which cleans `node_modules` but does not trigger the browser install postinstall script
- Multiple Playwright versions installed (global vs local)

**Fix**: Install the browsers.

```bash
# Install all browsers
npx playwright install

# Install only the browser you need (faster in CI)
npx playwright install chromium

# Install browsers with OS dependencies (needed in CI/Docker)
npx playwright install --with-deps

# If you're on a CI Dockerfile, add this to your Dockerfile
# RUN npx playwright install --with-deps chromium
```

For CI pipelines, always include the install step:

```yaml
# GitHub Actions example
- name: Install Playwright Browsers
  run: npx playwright install --with-deps
```

**Related**: [ci/ci-github-actions.md](../ci/ci-github-actions.md), [ci/docker-and-containers.md](../ci/docker-and-containers.md)

---

### "Error: Cannot use import statement outside a module"

**Cause**: Node.js is running the test file as CommonJS but the file uses ES module `import` syntax without the right configuration.

**Common triggers**:

- Missing or misconfigured `tsconfig.json`
- Using `.ts` files without `@playwright/test` properly resolving TypeScript
- `package.json` does not have `"type": "module"` but test files use `import`
- Running test files directly with `node` instead of through `npx playwright test`
- Conflicting Babel or ts-node configuration

**Fix**: Ensure TypeScript is configured correctly and always run tests through the Playwright CLI.

```bash
# Always run tests through the Playwright CLI — never with node directly
npx playwright test

# NOT this:
# node tests/example.spec.ts  <-- will fail
```

```typescript
// TypeScript — tsconfig.json (minimal working config)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

If using JavaScript without TypeScript:

```javascript
// JavaScript — ensure package.json has "type": "module"
// Or rename files to .mjs

// In playwright.config.js — use require if package.json lacks "type": "module"
const { defineConfig } = require("@playwright/test")
module.exports = defineConfig({
  /* ... */
})
```

**Related**: [core/configuration.md](configuration.md)

---

### "Error: fixture \"xxx\" has already been registered"

**Cause**: A custom fixture was defined with the same name in multiple `test.extend()` calls that got merged, or the same fixture name was registered twice in the same extension.

**Common triggers**:

- Two different fixture files both define a fixture with the same name
- Importing the extended `test` object from multiple files that each add overlapping fixtures
- Copy-pasting fixture definitions without renaming

**Fix**: Ensure each fixture name is unique across your merged fixture chain. Use a single fixture file that combines all extensions.

```typescript
// TypeScript

// BAD — two separate extensions with the same fixture name
// fixtures/auth.ts
export const test = base.extend<{ user: User }>({
  user: async ({}, use) => {
    /* ... */
  },
})

// fixtures/data.ts — CONFLICT: "user" already exists
export const test = base.extend<{ user: User }>({
  user: async ({}, use) => {
    /* ... */
  },
})

// GOOD — single combined fixture file
// fixtures/index.ts
import { test as base } from "@playwright/test"

type MyFixtures = {
  authenticatedUser: User
  testData: TestData
}

export const test = base.extend<MyFixtures>({
  authenticatedUser: async ({}, use) => {
    const user = await createUser()
    await use(user)
    await deleteUser(user)
  },
  testData: async ({}, use) => {
    const data = await seedData()
    await use(data)
    await cleanupData(data)
  },
})

export { expect } from "@playwright/test"
```

```javascript
// JavaScript

// GOOD — single combined fixture file
// fixtures/index.js
const { test: base } = require("@playwright/test")

const test = base.extend({
  authenticatedUser: async ({}, use) => {
    const user = await createUser()
    await use(user)
    await deleteUser(user)
  },
  testData: async ({}, use) => {
    const data = await seedData()
    await use(data)
    await cleanupData(data)
  },
})

module.exports = { test }
```

**Related**: [core/fixtures-and-hooks.md](fixtures-and-hooks.md)

---

## Network & API Errors

---

### "page.route: Pattern should start with..."

**Cause**: The URL pattern passed to `page.route()` does not match the expected format. Playwright expects a glob pattern (starting with `**/` or `http`), a regex, or a predicate function.

**Common triggers**:

- Passing a bare path like `/api/users` instead of `**/api/users`
- Missing the `**` glob prefix for relative patterns
- Passing an object or invalid type instead of a string/regex

**Fix**: Use the correct pattern format.

```typescript
// TypeScript

// BAD — bare path without glob prefix
await page.route("/api/users", (route) => route.fulfill({ body: "[]" }))

// GOOD — glob pattern
await page.route("**/api/users", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify([{ id: 1, name: "Alice" }]),
  })
)

// GOOD — regex pattern
await page.route(/\/api\/users\/\d+/, (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ id: 1, name: "Alice" }),
  })
)

// GOOD — predicate function for complex matching
await page.route(
  (url) => url.pathname.startsWith("/api/") && url.searchParams.has("filter"),
  (route) => route.fulfill({ body: "[]" })
)
```

```javascript
// JavaScript

// GOOD — glob pattern
await page.route("**/api/users", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify([{ id: 1, name: "Alice" }]),
  })
)

// GOOD — regex pattern
await page.route(/\/api\/users\/\d+/, (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ id: 1, name: "Alice" }),
  })
)

// GOOD — predicate function
await page.route(
  (url) => url.pathname.startsWith("/api/") && url.searchParams.has("filter"),
  (route) => route.fulfill({ body: "[]" })
)
```

**Related**: [core/network-mocking.md](network-mocking.md)

---

### "Error: apiRequestContext.get: connect ECONNREFUSED"

**Cause**: The API request made via `request.get()` (or `.post()`, `.put()`, etc.) could not connect to the target server. Same underlying issue as `page.goto: net::ERR_CONNECTION_REFUSED` but for API testing.

**Common triggers**:

- API server not running when using `request` fixture
- Wrong `baseURL` in the config or in the API request context
- Running API tests against a service that hasn't started yet
- In CI, the API service container is not ready

**Fix**: Ensure the API server is running. Use `webServer` config to auto-start it, or add a health check.

```typescript
// TypeScript — playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  webServer: [
    {
      command: "npm run start:api",
      url: "http://localhost:4000/health",
      reuseExistingServer: !process.env.CI,
    },
    {
      command: "npm run start:web",
      url: "http://localhost:3000",
      reuseExistingServer: !process.env.CI,
    },
  ],
  use: {
    baseURL: "http://localhost:3000",
  },
})

// In tests, use the request fixture with explicit baseURL for API calls
test("fetch users", async ({ request }) => {
  const response = await request.get("http://localhost:4000/api/users")
  expect(response.ok()).toBeTruthy()
})
```

```javascript
// JavaScript — playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  webServer: [
    {
      command: "npm run start:api",
      url: "http://localhost:4000/health",
      reuseExistingServer: !process.env.CI,
    },
    {
      command: "npm run start:web",
      url: "http://localhost:3000",
      reuseExistingServer: !process.env.CI,
    },
  ],
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

**Related**: [core/api-testing.md](api-testing.md), [core/configuration.md](configuration.md)

---

### "Request was not handled: GET https://..."

**Cause**: A route handler was registered with `page.route()` using `{ times: N }` or `page.unrouteAll()` was called, and a subsequent request matching that pattern was not intercepted — Playwright warns you that a request fell through.

**Common triggers**:

- Using `page.route()` with `{ times: 1 }` but the app makes the same request more than once
- Calling `route.fallback()` or `route.continue()` without a handler to catch it
- Calling `page.unrouteAll({ behavior: 'wait' })` mid-test and the app makes another request

**Fix**: Ensure your route handler covers all expected requests, or let unhandled requests pass through.

```typescript
// TypeScript

// BAD — only handles the first request, second one is unhandled
await page.route("**/api/data", (route) => route.fulfill({ body: "{}" }), { times: 1 })

// GOOD — handle all requests to this URL
await page.route("**/api/data", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ items: [] }),
  })
)

// GOOD — if you only want to intercept once, use waitForResponse for subsequent
await page.route("**/api/data", (route) => route.fulfill({ body: '{"items": []}' }), { times: 1 })
// For the second call, let it go to the real server (no route needed)
```

```javascript
// JavaScript

// GOOD — handle all requests to this URL
await page.route("**/api/data", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ items: [] }),
  })
)
```

**Related**: [core/network-mocking.md](network-mocking.md)

---

## Authentication & State Errors

---

### "Error: browserContext.storageState: No such file"

**Cause**: The `storageState` path referenced in the config or test does not point to an existing file. The auth state file has not been generated yet.

**Common triggers**:

- Running tests before running the auth setup project
- The `globalSetup` or auth setup project did not complete successfully
- The file path in the config does not match the path used in the setup
- `.gitignore` excluded the storage state file and it was not regenerated after a fresh clone
- CI cache expired and the state file was not recreated

**Fix**: Ensure the auth setup runs first and the file path is consistent.

```typescript
// TypeScript — playwright.config.ts
import { defineConfig } from "@playwright/test"

const authFile = "playwright/.auth/user.json"

export default defineConfig({
  projects: [
    // Setup project runs first and creates the auth state file
    {
      name: "setup",
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: "chromium",
      use: {
        storageState: authFile,
      },
      dependencies: ["setup"], // ensures setup runs first
    },
  ],
})

// auth.setup.ts
import { test as setup, expect } from "@playwright/test"

const authFile = "playwright/.auth/user.json"

setup("authenticate", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill("user@example.com")
  await page.getByLabel("Password").fill("password123")
  await page.getByRole("button", { name: "Sign in" }).click()
  await page.waitForURL("/dashboard")
  // Save the authenticated state
  await page.context().storageState({ path: authFile })
})
```

```javascript
// JavaScript — playwright.config.js
const { defineConfig } = require("@playwright/test")

const authFile = "playwright/.auth/user.json"

module.exports = defineConfig({
  projects: [
    {
      name: "setup",
      testMatch: /.*\.setup\.js/,
    },
    {
      name: "chromium",
      use: {
        storageState: authFile,
      },
      dependencies: ["setup"],
    },
  ],
})

// auth.setup.js
const { test: setup, expect } = require("@playwright/test")

const authFile = "playwright/.auth/user.json"

setup("authenticate", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill("user@example.com")
  await page.getByLabel("Password").fill("password123")
  await page.getByRole("button", { name: "Sign in" }).click()
  await page.waitForURL("/dashboard")
  await page.context().storageState({ path: authFile })
})
```

Ensure the auth directory exists and is in `.gitignore`:

```bash
mkdir -p playwright/.auth
echo "playwright/.auth/" >> .gitignore
```

**Related**: [core/authentication.md](authentication.md), [core/auth-flows.md](auth-flows.md)

---

### "Error: Target page, context or browser has been closed"

**Cause**: Code attempted to use a `page`, `context`, or `browser` object that has already been closed or disposed.

**Common triggers**:

- Using a `page` reference after `page.close()` was called
- Storing a `page` or `context` in a module-level variable and reusing it across tests
- A fixture tore down the browser context while an async callback was still running
- A `beforeAll` created a context that was closed before all tests finished using it
- Using `browser.newContext()` manually and forgetting to manage its lifecycle

**Fix**: Never store page/context references in shared mutable state. Use Playwright fixtures for lifecycle management.

```typescript
// TypeScript

// BAD — shared module-level variable
let sharedPage: Page
test.beforeAll(async ({ browser }) => {
  sharedPage = await browser.newPage()
})
test.afterAll(async () => {
  await sharedPage.close()
})
test("first", async () => {
  await sharedPage.goto("/") // might fail if afterAll from another describe ran first
})

// GOOD — use the built-in page fixture (one per test, auto-managed)
test("first", async ({ page }) => {
  await page.goto("/") // always a fresh, open page
})

// GOOD — for shared state across tests, use a worker-scoped fixture
import { test as base } from "@playwright/test"

export const test = base.extend<{}, { adminContext: BrowserContext }>({
  adminContext: [
    async ({ browser }, use) => {
      const context = await browser.newContext()
      await use(context)
      await context.close()
    },
    { scope: "worker" },
  ],
})
```

```javascript
// JavaScript

// GOOD — use the built-in page fixture
test("first", async ({ page }) => {
  await page.goto("/")
})

// GOOD — for shared state, use a worker-scoped fixture
const { test: base } = require("@playwright/test")

const test = base.extend({
  adminContext: [
    async ({ browser }, use) => {
      const context = await browser.newContext()
      await use(context)
      await context.close()
    },
    { scope: "worker" },
  ],
})
```

**Related**: [core/fixtures-and-hooks.md](fixtures-and-hooks.md)

---

## CI-Specific Errors

---

### "Error: browserType.launch: Browser closed unexpectedly"

**Cause**: The browser process crashed immediately after launch, usually because required OS-level dependencies are missing in the CI environment.

**Common triggers**:

- Running on a minimal Docker image (e.g., `node:alpine`) without browser dependencies
- Missing shared libraries (`libgbm`, `libnss3`, `libatk-bridge`, etc.) on Linux CI
- Insufficient shared memory (`/dev/shm` too small) — browsers use shared memory for rendering
- Running as root in Docker without `--no-sandbox` (Chromium refuses to run as root with sandbox)
- Out-of-memory kill on CI (browser process is OOM-killed by the OS)

**Fix**: Install OS-level dependencies and configure the environment.

```bash
# Install browsers with their OS dependencies (recommended)
npx playwright install --with-deps chromium

# If using Docker, use the official Playwright image
# Dockerfile
FROM mcr.microsoft.com/playwright:v1.50.0-noble
WORKDIR /app
COPY . .
RUN npm ci
RUN npx playwright install chromium
CMD ["npx", "playwright", "test"]
```

For shared memory issues:

```yaml
# GitHub Actions — increase /dev/shm
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.50.0-noble
      options: --shm-size=2gb

# Docker run — increase shared memory
# docker run --shm-size=2gb my-test-image
```

For running as root in Docker:

```typescript
// TypeScript — playwright.config.ts (only for Docker/CI)
export default defineConfig({
  use: {
    launchOptions: {
      args: process.env.CI ? ["--no-sandbox", "--disable-setuid-sandbox"] : [],
    },
  },
})
```

```javascript
// JavaScript — playwright.config.js
module.exports = defineConfig({
  use: {
    launchOptions: {
      args: process.env.CI ? ["--no-sandbox", "--disable-setuid-sandbox"] : [],
    },
  },
})
```

**Related**: [ci/ci-github-actions.md](../ci/ci-github-actions.md), [ci/docker-and-containers.md](../ci/docker-and-containers.md)

---

### "Error: Playwright Test needs to be invoked via 'npx playwright test'"

**Cause**: The test file was executed directly with `node` or `ts-node` instead of through the Playwright test runner.

**Common triggers**:

- Running `node tests/example.spec.ts` or `ts-node tests/example.spec.ts`
- A misconfigured IDE run configuration that invokes `node` directly
- Using Jest or Mocha to run Playwright test files that import from `@playwright/test`
- A CI script that calls the wrong command

**Fix**: Always use the Playwright CLI to run tests.

```bash
# Correct invocations
npx playwright test                           # run all tests
npx playwright test tests/login.spec.ts       # run specific file
npx playwright test --grep "login"            # run tests matching pattern
npx playwright test --project=chromium        # run specific project
npx playwright test --debug                   # run with inspector

# If using a package.json script
# package.json
# "scripts": { "test:e2e": "playwright test" }
npm run test:e2e
```

For IDE configuration (VS Code):

```json
// .vscode/settings.json — install the Playwright VS Code extension instead of custom configs
{
  "playwright.reuseBrowser": true
}
```

**Related**: [core/configuration.md](configuration.md)

---

## Additional Common Errors

---

### "Error: page.evaluate: Execution context was destroyed"

**Cause**: The page navigated or reloaded while `page.evaluate()` was executing JavaScript in the browser context.

**Common triggers**:

- Calling `evaluate()` while the page is in the middle of a navigation
- A timer or event on the page triggers a redirect during evaluation
- Running `evaluate()` in a `beforeEach` that races with `page.goto()`

**Fix**: Ensure the page is stable before evaluating.

```typescript
// TypeScript

// BAD — evaluate races with navigation
await page.goto("/dashboard")
const title = await page.evaluate(() => document.title) // context might be destroyed

// GOOD — wait for load state first
await page.goto("/dashboard")
await page.waitForLoadState("domcontentloaded")
const title = await page.evaluate(() => document.title)

// GOOD — prefer locator-based assertions (no evaluate needed)
await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard")
```

```javascript
// JavaScript

// GOOD — wait for load state first
await page.goto("/dashboard")
await page.waitForLoadState("domcontentloaded")
const title = await page.evaluate(() => document.title)

// GOOD — prefer locator-based assertions
await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard")
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "Error: page.screenshot: Cannot take a screenshot larger than..."

**Cause**: The requested screenshot dimensions exceed Playwright's limit (typically 16384x16384 pixels). This happens with full-page screenshots of very long pages.

**Common triggers**:

- `page.screenshot({ fullPage: true })` on an infinitely-scrolling page
- Pages with extremely tall content (long data tables, chat logs)
- CSS bugs that create enormous element heights

**Fix**: Clip the screenshot to a specific region or limit the viewport.

```typescript
// TypeScript

// BAD — might exceed size limits on tall pages
await page.screenshot({ fullPage: true, path: "full.png" })

// GOOD — clip to a specific region
await page.screenshot({
  path: "clipped.png",
  clip: { x: 0, y: 0, width: 1280, height: 2000 },
})

// GOOD — screenshot a specific element instead
await page.getByRole("main").screenshot({ path: "main-content.png" })

// GOOD — set a reasonable viewport before full-page screenshot
await page.setViewportSize({ width: 1280, height: 720 })
await page.screenshot({ fullPage: true, path: "full.png" })
```

```javascript
// JavaScript

// GOOD — clip to a specific region
await page.screenshot({
  path: "clipped.png",
  clip: { x: 0, y: 0, width: 1280, height: 2000 },
})

// GOOD — screenshot a specific element
await page.getByRole("main").screenshot({ path: "main-content.png" })
```

**Related**: [core/visual-regression.md](visual-regression.md)

---

### "Error: waiting for locator('...').toBeAttached()"

**Cause**: The element never entered the DOM within the assertion timeout. Unlike `toBeVisible()`, `toBeAttached()` only checks DOM presence — but the element was never rendered at all.

**Common triggers**:

- The component is conditionally rendered and the condition is not met
- A network request that populates the data has not completed
- Wrong selector that does not match any element
- The element is rendered by a lazy-loaded chunk that has not downloaded yet

**Fix**: Verify the precondition for the element to render.

```typescript
// TypeScript

// Ensure the data loads before asserting
await page.goto("/users")
await page.waitForResponse((resp) => resp.url().includes("/api/users"))
await expect(page.getByRole("table")).toBeAttached()

// For lazy-loaded content, wait longer or trigger the load
await page.getByRole("tab", { name: "Advanced" }).click()
await expect(page.getByTestId("advanced-panel")).toBeAttached({ timeout: 10_000 })
```

```javascript
// JavaScript

await page.goto("/users")
await page.waitForResponse((resp) => resp.url().includes("/api/users"))
await expect(page.getByRole("table")).toBeAttached()

await page.getByRole("tab", { name: "Advanced" }).click()
await expect(page.getByTestId("advanced-panel")).toBeAttached({ timeout: 10_000 })
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/locators.md](locators.md)

---

### "Error: protocol error: Target.createTarget: Failed to create target"

**Cause**: The browser could not create a new tab or context, usually due to resource exhaustion.

**Common triggers**:

- Opening too many pages or contexts without closing them
- Memory leak in tests — each test opens a context but never closes it
- Running many parallel workers on a resource-constrained CI machine
- Browser process is unstable after a previous crash

**Fix**: Reduce parallelism, close unused contexts, or use fewer workers.

```typescript
// TypeScript — playwright.config.ts

export default defineConfig({
  // Reduce parallelism if resources are limited
  workers: process.env.CI ? 2 : undefined,

  // Limit to one browser context per worker
  fullyParallel: false, // run test files serially within a worker
})
```

```javascript
// JavaScript — playwright.config.js

module.exports = defineConfig({
  workers: process.env.CI ? 2 : undefined,
  fullyParallel: false,
})
```

If you manually create contexts, always close them:

```typescript
// TypeScript
test("multi-user test", async ({ browser }) => {
  const userContext = await browser.newContext()
  const adminContext = await browser.newContext()
  try {
    const userPage = await userContext.newPage()
    const adminPage = await adminContext.newPage()
    // ... test logic
  } finally {
    await userContext.close()
    await adminContext.close()
  }
})
```

```javascript
// JavaScript
test("multi-user test", async ({ browser }) => {
  const userContext = await browser.newContext()
  const adminContext = await browser.newContext()
  try {
    const userPage = await userContext.newPage()
    const adminPage = await adminContext.newPage()
    // ... test logic
  } finally {
    await userContext.close()
    await adminContext.close()
  }
})
```

**Related**: [ci/parallel-and-sharding.md](../ci/parallel-and-sharding.md), [core/multi-user-and-collaboration.md](multi-user-and-collaboration.md)

---

### "Error: expect(locator).toHaveText() — expected string but received array"

**Cause**: The locator matched multiple elements and `toHaveText()` returned an array of strings instead of a single string.

**Common triggers**:

- Using a broad locator like `page.locator('.item')` that matches a list
- Expecting a single heading but the selector matches multiple
- Not scoping the locator to a specific container

**Fix**: Either narrow the locator to one element or use the array form of `toHaveText()`.

```typescript
// TypeScript

// BAD — locator matches multiple elements
await expect(page.locator(".item")).toHaveText("First Item")

// GOOD — narrow to one element
await expect(page.locator(".item").first()).toHaveText("First Item")

// GOOD — assert against an array when multiple elements are expected
await expect(page.locator(".item")).toHaveText(["First Item", "Second Item", "Third Item"])

// GOOD — use a more specific locator
await expect(page.getByRole("heading", { level: 1 })).toHaveText("Welcome")
```

```javascript
// JavaScript

// GOOD — narrow to one element
await expect(page.locator(".item").first()).toHaveText("First Item")

// GOOD — assert against an array
await expect(page.locator(".item")).toHaveText(["First Item", "Second Item", "Third Item"])

// GOOD — use a more specific locator
await expect(page.getByRole("heading", { level: 1 })).toHaveText("Welcome")
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/locators.md](locators.md)

---

### "Error: page.waitForSelector: Timeout 30000ms exceeded (deprecated)"

**Cause**: `page.waitForSelector()` timed out. This method is deprecated in favor of locator-based assertions.

**Common triggers**:

- Using legacy `page.waitForSelector()` from older tutorials or migration from Puppeteer
- The selector does not match any element in the DOM
- The element exists but does not meet the state requirement (e.g., `{ state: 'visible' }` but element is hidden)

**Fix**: Replace `waitForSelector()` with locator-based assertions.

```typescript
// TypeScript

// BAD — deprecated, no auto-retry, not composable
await page.waitForSelector(".loading", { state: "hidden" })
await page.waitForSelector(".content", { state: "visible" })

// GOOD — locator-based assertions with auto-retry
await expect(page.locator(".loading")).toBeHidden()
await expect(page.locator(".content")).toBeVisible()

// GOOD — use role-based locators for even more resilience
await expect(page.getByRole("progressbar")).toBeHidden()
await expect(page.getByRole("main")).toBeVisible()
```

```javascript
// JavaScript

// BAD — deprecated
await page.waitForSelector(".loading", { state: "hidden" })
await page.waitForSelector(".content", { state: "visible" })

// GOOD — locator-based assertions
await expect(page.locator(".loading")).toBeHidden()
await expect(page.locator(".content")).toBeVisible()

// GOOD — role-based locators
await expect(page.getByRole("progressbar")).toBeHidden()
await expect(page.getByRole("main")).toBeVisible()
```

**Related**: [core/locators.md](locators.md), [core/assertions-and-waiting.md](assertions-and-waiting.md), [migration/from-selenium.md](../migration/from-selenium.md)

---

### "Error: Test was expected to have a title matching /.../"

**Cause**: The `expect(page).toHaveTitle()` assertion failed because the page title did not match the expected value or pattern within the timeout.

**Common triggers**:

- The page has not finished loading and the title is still the initial empty or default value
- The SPA updates the document title asynchronously after rendering
- The expected title has a typo or does not match case-sensitively
- The page redirected to an error page with a different title

**Fix**: Ensure the page is fully loaded and use the correct expected value.

```typescript
// TypeScript

// toHaveTitle auto-retries, but ensure the page has loaded
await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard | MyApp")

// Use regex for flexible matching
await expect(page).toHaveTitle(/Dashboard/)

// Debug: check what the actual title is
console.log(await page.title())
```

```javascript
// JavaScript

await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard | MyApp")

// Use regex for flexible matching
await expect(page).toHaveTitle(/Dashboard/)

// Debug: check what the actual title is
console.log(await page.title())
```

**Related**: [core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "Error: page.type: Element is not focusable"

**Cause**: `page.type()` or `locator.type()` could not focus the target element before typing. The element may be hidden, disabled, or not an input.

**Common triggers**:

- The element is covered by an overlay or modal
- The element has `tabindex="-1"` and is not natively focusable
- Using `type()` instead of `fill()` — `fill()` is preferred in almost all cases
- The element is inside a Shadow DOM and the locator does not pierce it

**Fix**: Use `fill()` instead of `type()`. Only use `type()` when you specifically need to simulate individual keystrokes.

```typescript
// TypeScript

// BAD — type() is slower and more fragile
await page.locator("#search").type("hello")

// GOOD — fill() clears and sets the value directly
await page.getByRole("searchbox").fill("hello")

// When you truly need keystroke-by-keystroke input (e.g., autocomplete trigger)
await page.getByRole("searchbox").pressSequentially("hello", { delay: 100 })
```

```javascript
// JavaScript

// GOOD — fill() is preferred
await page.getByRole("searchbox").fill("hello")

// Keystroke-by-keystroke when needed (e.g., autocomplete)
await page.getByRole("searchbox").pressSequentially("hello", { delay: 100 })
```

**Related**: [core/locators.md](locators.md), [core/forms-and-validation.md](forms-and-validation.md)

---

### "Error: page.setInputFiles: Non-multiple file input can only accept single file"

**Cause**: Attempted to upload multiple files to an `<input type="file">` that does not have the `multiple` attribute.

**Common triggers**:

- Passing an array of files to a single-file upload input
- The app uses a custom upload component that only handles one file at a time

**Fix**: Upload one file at a time, or ensure the input supports multiple files.

```typescript
// TypeScript

// BAD — input does not have multiple attribute
await page.getByLabel("Upload file").setInputFiles([
  "file1.pdf",
  "file2.pdf", // error: non-multiple input
])

// GOOD — single file
await page.getByLabel("Upload file").setInputFiles("file1.pdf")

// GOOD — for multiple file input (must have multiple attribute in HTML)
await page.getByLabel("Upload files").setInputFiles(["file1.pdf", "file2.pdf"])

// To clear the file input
await page.getByLabel("Upload file").setInputFiles([])
```

```javascript
// JavaScript

// GOOD — single file
await page.getByLabel("Upload file").setInputFiles("file1.pdf")

// GOOD — multiple files (input must have multiple attribute)
await page.getByLabel("Upload files").setInputFiles(["file1.pdf", "file2.pdf"])

// To clear the file input
await page.getByLabel("Upload file").setInputFiles([])
```

**Related**: [core/file-operations.md](file-operations.md), [core/file-upload-download.md](file-upload-download.md)

---

### "Error: browser.newContext: Could not parse content-type application/json"

**Cause**: The `storageState` option was given a path to a file with invalid JSON content, or the file is not a valid Playwright storage state format.

**Common triggers**:

- The auth setup wrote an empty file or incomplete JSON
- The storage state file was corrupted or truncated
- Manually editing the storage state file and introducing a syntax error
- The auth setup failed silently (login did not complete) and saved an invalid state

**Fix**: Delete the storage state file and regenerate it.

```bash
# Delete the corrupted file
rm -f playwright/.auth/user.json

# Re-run the setup
npx playwright test --project=setup
```

To prevent this, add error checking in the auth setup:

```typescript
// TypeScript — auth.setup.ts
import { test as setup, expect } from "@playwright/test"

const authFile = "playwright/.auth/user.json"

setup("authenticate", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill("user@example.com")
  await page.getByLabel("Password").fill("password123")
  await page.getByRole("button", { name: "Sign in" }).click()

  // Verify login actually succeeded before saving state
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  await page.context().storageState({ path: authFile })
})
```

```javascript
// JavaScript — auth.setup.js
const { test: setup, expect } = require("@playwright/test")

const authFile = "playwright/.auth/user.json"

setup("authenticate", async ({ page }) => {
  await page.goto("/login")
  await page.getByLabel("Email").fill("user@example.com")
  await page.getByLabel("Password").fill("password123")
  await page.getByRole("button", { name: "Sign in" }).click()

  // Verify login actually succeeded before saving state
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  await page.context().storageState({ path: authFile })
})
```

**Related**: [core/authentication.md](authentication.md), [core/auth-flows.md](auth-flows.md)

---

## Quick Diagnostic Checklist

When you hit an error not listed above, run through this checklist:

1. **Read the full error** — Playwright errors include the locator, action, and a snippet of the page state. The answer is often in the details.
2. **Enable traces** — Add `trace: 'on'` temporarily or `trace: 'on-first-retry'` in config. Run `npx playwright show-trace trace.zip` to see screenshots, DOM, network, and console at the point of failure.
3. **Use the Playwright Inspector** — Run `npx playwright test --debug` to step through the test interactively.
4. **Check the locator** — Run `npx playwright codegen <url>` to verify locators against the live page.
5. **Check the Playwright version** — Run `npx playwright --version`. Ensure `@playwright/test` and browser binaries are the same version.
6. **Search the Playwright issue tracker** — Many errors have known solutions in [github.com/microsoft/playwright/issues](https://github.com/microsoft/playwright/issues).