diff --git a/packages/effect/src/Effect.ts b/packages/effect/src/Effect.ts
index 6ac1ca3a9..fe3b9df85 100644
--- a/packages/effect/src/Effect.ts
+++ b/packages/effect/src/Effect.ts
@@ -2662,13 +2662,14 @@ export const catchDefect: {
  * @example
  * ```ts
  * import { Effect } from "effect"
+ * import { Filter } from "effect/data"
  *
  * // An effect that might fail with a number
  * const program = Effect.fail(42)
  *
  * // Recover only from specific error values
  * const recovered = Effect.catchFilter(program,
- *   (error) => error === 42,
+ *   (error) => error === 42 ? error : Filter.fail(error),
  *   (error) => Effect.succeed(`Recovered from error: ${error}`)
  * )
  * ```
@@ -2697,15 +2698,14 @@ export const catchFilter: {
  *
  * @example
  * ```ts
- * import { Effect, Cause } from "effect"
- * import { Console } from "effect"
+ * import { Cause, Console, Effect } from "effect"
  *
  * const httpRequest = Effect.fail("Network Error")
  *
  * // Only catch network-related failures
  * const program = Effect.catchCauseFilter(
  *   httpRequest,
- *   (cause) => Cause.hasFail(cause),
+ *   (cause) => Cause.filterFail(cause),
  *   (failure, cause) => Effect.gen(function* () {
  *     yield* Console.log(`Caught network error: ${Cause.squash(cause)}`)
  *     return "Fallback response"
@@ -2938,15 +2938,14 @@ export const tapCause: {
  *
  * @example
  * ```ts
- * import { Effect, Cause } from "effect"
- * import { Console } from "effect"
+ * import { Cause, Console, Effect } from "effect"
  *
  * const task = Effect.fail("Network timeout")
  *
  * // Only log causes that contain failures (not interrupts or defects)
  * const program = Effect.tapCauseFilter(
  *   task,
- *   (cause) => Cause.hasFail(cause),
+ *   (cause) => Cause.filterFail(cause),
  *   (_, cause) =>
  *     Console.log(`Logging failure cause: ${Cause.squash(cause)}`)
  * )
diff --git a/packages/effect/src/stream/Channel.ts b/packages/effect/src/stream/Channel.ts
index 324bb0f01..dab32e058 100644
--- a/packages/effect/src/stream/Channel.ts
+++ b/packages/effect/src/stream/Channel.ts
@@ -2787,20 +2787,22 @@ export const drain = <
  *
  * @example
  * ```ts
+ * import { Filter } from "effect/data"
  * import { Channel } from "effect/stream"
- * import { Effect } from "effect"
  *
  * // Create a channel with mixed numbers
  * const numbersChannel = Channel.fromIterable([1, 2, 3, 4, 5, 6, 7, 8])
  *
  * // Filter to keep only even numbers
- * const evenChannel = Channel.filter(numbersChannel, (n) => n % 2 === 0)
+ * const evenChannel = Channel.filter(numbersChannel, (n) =>
+ *   n % 2 === 0 ? n : Filter.fail(n)
+ * )
  * // Outputs: 2, 4, 6, 8
  *
  * // Filter with type refinement
  * const mixedChannel = Channel.fromIterable([1, "hello", 2, "world", 3])
  * const numbersOnlyChannel = Channel.filter(mixedChannel,
- *   (value): value is number => typeof value === "number"
+ *   (value) => typeof value === "number" ? value : Filter.fail(value)
  * )
  * // Outputs: 1, 2, 3 (all typed as numbers)
  * ```
@@ -2860,7 +2862,9 @@ export const filter: {
  * ]).pipe(Channel.filter(nonEmptyArrayFilter))
  *
  * // Filter arrays to keep only even numbers
- * const evenArraysChannel = Channel.filterArray(arrayChannel, (n) => n % 2 === 0)
+ * const evenArraysChannel = Channel.filterArray(arrayChannel, (n) =>
+ *   n % 2 === 0 ? n : Filter.fail(n)
+ * )
  * // Outputs: [2, 4], [6, 8, 10], [12, 14]
  * // Note: Only non-empty filtered arrays are emitted
  *
@@ -2868,7 +2872,9 @@ export const filter: {
  * const oddChannel = Channel.fromIterable([[1, 3, 5], [2, 4], [7, 9]]).pipe(
  *   Channel.filter(nonEmptyArrayFilter)
  * )
- * const filteredOddChannel = Channel.filterArray(oddChannel, (n) => n % 2 === 0)
+ * const filteredOddChannel = Channel.filterArray(oddChannel, (n) =>
+ *   n % 2 === 0 ? n : Filter.fail(n)
+ * )
  * // Outputs: [2, 4] (the arrays [1,3,5] and [7,9] are discarded)
  * ```
  *
diff --git a/packages/effect/src/stream/Stream.ts b/packages/effect/src/stream/Stream.ts
index f470c67a7..ed4ccd4a6 100644
--- a/packages/effect/src/stream/Stream.ts
+++ b/packages/effect/src/stream/Stream.ts
@@ -2564,15 +2564,14 @@ export const mapError: {
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Cause, Effect } from "effect"
  * import { Stream } from "effect/stream"
- * import { Cause } from "effect"
  *
  * const failingStream = Stream.fail("NetworkError")
  *
  * const recovered = Stream.catchCauseFilter(
  *   failingStream,
- *   Cause.hasFail,
+ *   (cause) => Cause.filterFail(cause),
  *   (error, cause) => Stream.make("Recovered from network error")
  * )
  * ```