@@ -118,6 +118,13 @@ The callback receives an `AbortSignal` that is aborted when the poll timeout is
 
 If an error is thrown inside the `expect.poll` callback, Vitest will retry again until the timeout runs out.
 
+The `message` option describes what the poll waits for. If the poll fails, Vitest adds the message to the start of the error.
+
+```ts
+await expect.poll(() => queue.count(), { message: 'queue drained' }).toBe(0)
+// AssertionError: queue drained: expected 3 to be 0 // Object.is equality
+```
+
 If `vi.useFakeTimers` is used, `expect.poll` automatically calls `vi.advanceTimersByTime(interval)` after every failed attempt. See [Automatic Advancing](/guide/mocking/timers#automatic-advancing) for details.
 
 ```ts
 
@@ -28,15 +28,24 @@ const unsupported = [
 ]
 
 /**
- * Attaches a `cause` property to the error if missing, copies the stack trace from the source, and throws.
+ * Attaches a `cause` property to the error if missing, prefixes the custom message, copies the stack trace from the source, and throws.
  *
  * @param error - The error to throw
  * @param source - Error to copy the stack trace from
+ * @param message - Custom message passed to `expect.poll`
  *
  * @throws Always throws the provided error with an amended stack trace
  */
-function throwWithCause(error: any, source: Error) {
+function throwWithCause(error: any, source: Error, message: string | undefined) {
   error.cause ??= new Error('Matcher did not succeed in time.')
+  // matcher errors already start with the custom message
+  if (message && typeof error.message === 'string' && !error.message.startsWith(`${message}: `)) {
+    try {
+      error.message = `${message}: ${error.message}`
+    } catch {
+      // message can be read-only, e.g. DOMException
+    }
+  }
 
   throw copyStackTrace(error, source)
 }
@@ -124,7 +133,7 @@ export function createExpectPoll(expect: ExpectStatic): ExpectStatic['poll'] {
                 return output
               } catch (err) {
                 await onSettled?.({ assertion, status: 'fail' })
-                throwWithCause(err, STACK_TRACE_ERROR)
+                throwWithCause(err, STACK_TRACE_ERROR, message)
               }
             }
 
@@ -186,7 +195,7 @@ export function createExpectPoll(expect: ExpectStatic): ExpectStatic['poll'] {
             }
             if (lastError) {
               await onSettled?.({ assertion, status: 'fail' })
-              throwWithCause(lastError, STACK_TRACE_ERROR)
+              throwWithCause(lastError, STACK_TRACE_ERROR, message)
             }
           }
           let awaited = false
 
@@ -144,6 +144,39 @@ test('custom message', async () => {
   )
 })
 
+test('custom message on callback errors', async () => {
+  const callbackError = new Error('db closed')
+  const error = await expect
+    .poll(
+      () => {
+        throw callbackError
+      },
+      { timeout: 100, interval: 10, message: 'custom' },
+    )
+    .toBe(2)
+    .catch((e) => e)
+  expect(error).toBe(callbackError)
+  expect(error).toMatchInlineSnapshot(`[Error: custom: db closed]`)
+  expect(error.cause).toMatchInlineSnapshot(`[Error: Matcher did not succeed in time.]`)
+
+  // read-only message is left as is
+  const domError = await expect
+    .poll(
+      () => {
+        throw new DOMException('aborted', 'AbortError')
+      },
+      { timeout: 100, interval: 10, message: 'custom' },
+    )
+    .toBe(2)
+    .catch((e) => e)
+  expect(domError).toBeInstanceOf(DOMException)
+  expect(domError.message).toBe('aborted')
+
+  await expect(() =>
+    expect.poll(() => new Promise(() => {}), { timeout: 50, message: 'custom' }).toBe(2),
+  ).rejects.toMatchInlineSnapshot(`[Error: custom: expect.poll() function didn't resolve in time.]`)
+})
+
 test('unresolved function', async () => {
   let aborted = false
   await expect(
Original file line number	Diff line number	Diff line change
`@@ -28,15 +28,24 @@ const unsupported = [`
`28`	`28`	`]`
`29`	`29`
`30`	`30`	`/**`
`31`		- * Attaches a `cause` property to the error if missing, copies the stack trace from the source, and throws.
	`31`	+ * Attaches a `cause` property to the error if missing, prefixes the custom message, copies the stack trace from the source, and throws.
`32`	`32`	`*`
`33`	`33`	`* @param error - The error to throw`
`34`	`34`	`* @param source - Error to copy the stack trace from`
	`35`	+ * @param message - Custom message passed to `expect.poll`
`35`	`36`	`*`
`36`	`37`	`* @throws Always throws the provided error with an amended stack trace`
`37`	`38`	`*/`
`38`		`-function throwWithCause(error: any, source: Error) {`
	`39`	`+function throwWithCause(error: any, source: Error, message: string \| undefined) {`
`39`	`40`	`error.cause ??= new Error('Matcher did not succeed in time.')`
	`41`	`+ // matcher errors already start with the custom message`
	`42`	+ if (message && typeof error.message === 'string' && !error.message.startsWith(`${message}: `)) {
	`43`	`+ try {`
	`44`	+ error.message = `${message}: ${error.message}`
	`45`	`+ } catch {`
	`46`	`+ // message can be read-only, e.g. DOMException`
	`47`	`+ }`
	`48`	`+ }`
`40`	`49`
`41`	`50`	`throw copyStackTrace(error, source)`
`42`	`51`	`}`
`@@ -124,7 +133,7 @@ export function createExpectPoll(expect: ExpectStatic): ExpectStatic['poll'] {`
`124`	`133`	`return output`
`125`	`134`	`} catch (err) {`
`126`	`135`	`await onSettled?.({ assertion, status: 'fail' })`
`127`		`- throwWithCause(err, STACK_TRACE_ERROR)`
	`136`	`+ throwWithCause(err, STACK_TRACE_ERROR, message)`
`128`	`137`	`}`
`129`	`138`	`}`
`130`	`139`
`@@ -186,7 +195,7 @@ export function createExpectPoll(expect: ExpectStatic): ExpectStatic['poll'] {`
`186`	`195`	`}`
`187`	`196`	`if (lastError) {`
`188`	`197`	`await onSettled?.({ assertion, status: 'fail' })`
`189`		`- throwWithCause(lastError, STACK_TRACE_ERROR)`
	`198`	`+ throwWithCause(lastError, STACK_TRACE_ERROR, message)`
`190`	`199`	`}`
`191`	`200`	`}`
`192`	`201`	`let awaited = false`