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

# Troubleshooting

> Troubleshoot common @qawolf/emails problems, including missing client configuration, stale messages, and inbox wait timeouts.

## `mail.inbox()` throws because no client is configured

Cause: The runtime did not call `configureEmailsClient(...)` before the flow ran.

Check:

* the runner creates the client
* the runner configures it before flow execution

## `waitForMessage(...)` returns an older message

Check:

* whether the flow should pass `after: new Date()`
* whether the same inbox is being reused across multiple steps or retries

## No message arrives before timeout

Check:

* the product under test actually sent the email
* the address being used is allowed for the workspace
* the timeout is long enough for the expected delivery path

## Old emails are matched by waitForMessage

Using `new: true` to generate a unique address for each run ensures `waitForMessage` only sees messages from the current run.

When reusing a stable address is unavoidable, pass `after: new Date()` immediately before the action that triggers the email:

```javascript theme={null}
const after = new Date();
await page.getByRole("button", { name: "Send code" }).click();

const message = await inbox.waitForMessage({ after });
```

For a local harness where neither option is available, calling `resetEmailsClient()` between test suites clears the client state.