Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(replay-vision): show scanner filter errors instead of retrying them (#126630)

Tue Haulund7ca3f868d35d
diff --git a/posthog/models/activity_logging/activity_log.py b/posthog/models/activity_logging/activity_log.py
index c85747281ffe..aab9e104ccbf 100644
--- a/posthog/models/activity_logging/activity_log.py
+++ b/posthog/models/activity_logging/activity_log.py
@@ -561,6 +561,8 @@ replay_scanner_machine_fields = [
"estimated_monthly_observations",
"estimated_at",
"estimate_attempted_at",
+ "filter_error",
+ "filter_error_at",
"prompt_question",
"prompt_question_source",
"prompt_valence",
diff --git a/products/replay_vision/backend/api/scanners.py b/products/replay_vision/backend/api/scanners.py
index 370ff862fb37..e476adca6625 100644
--- a/products/replay_vision/backend/api/scanners.py
+++ b/products/replay_vision/backend/api/scanners.py
@@ -120,6 +120,7 @@ from products.replay_vision.backend.queries import (
project_monthly_observations,
refresh_scanner_estimate,
)
+from products.replay_vision.backend.queries.filter_errors import REDACTED_FILTER_ERROR, filter_error_message
from products.replay_vision.backend.quota import (
ScannerBudget,
ScannerSpend,
@@ -345,8 +346,15 @@ def _refresh_estimate_fail_soft(scanner: ReplayScanner) -> None:
# The scanner's own query no longer builds, for example a deleted action or a bad
# cohort reference. No launch heals that, so keep it in error tracking.
logger.exception("replay_vision.estimate_refresh_failed", scanner_id=str(scanner.id))
- except Exception:
- logger.exception("replay_vision.estimate_refresh_failed", scanner_id=str(scanner.id))
+ except Exception as error:
+ message = filter_error_message(error)
+ if message is None:
+ logger.exception("replay_vision.estimate_refresh_failed", scanner_id=str(scanner.id))
+ else:
+ # The first sweep records it on the scanner, since the estimate's wider query can fail
+ # where the sweep's does not.
+ record_estimate_outcome("filter_error")
+ logger.warning("replay_vision.estimate_filter_error", scanner_id=str(scanner.id), reason=message)
else:
record_estimate_outcome("refreshed")
@@ -652,6 +660,7 @@ class ReplayScannerSerializer(TaggedItemSerializerMixin, UserAccessControlSerial
"dashboard_id",
"dashboard_suggested",
"last_swept_at",
+ "filter_error",
"created_at",
"created_by",
"updated_at",
@@ -674,6 +683,7 @@ class ReplayScannerSerializer(TaggedItemSerializerMixin, UserAccessControlSerial
"dashboard_id",
"dashboard_suggested",
"last_swept_at",
+ "filter_error",
"created_at",
"created_by",
"updated_at",
@@ -989,6 +999,9 @@ class ReplayScannerSerializer(TaggedItemSerializerMixin, UserAccessControlSerial
# check in validate_experiment_targeting — a caller without experiment access sees null.
if data.get("experiment_targeting") and not self._can_view_targeted_experiment(data["experiment_targeting"]):
data["experiment_targeting"] = None
+ # The query error can quote the experiment's exposure filter, so a denied caller gets the fact only.
+ if data.get("filter_error"):
+ data["filter_error"] = REDACTED_FILTER_ERROR
# The experiment type keeps its scope in scanner_config; hide only the experiment keys from
# a denied caller, so the rest of the config (prompt, length) stays readable. Writes are a
# separate question: `_restore_redacted_experiment_config` refuses every config write from a
@@ -1001,6 +1014,8 @@ class ReplayScannerSerializer(TaggedItemSerializerMixin, UserAccessControlSerial
for key, value in data["scanner_config"].items()
if key not in ("experiment_id", "variants")
}
+ if data.get("filter_error"):
+ data["filter_error"] = REDACTED_FILTER_ERROR
return data
def _can_view_targeted_experiment(self, targeting: dict[str, Any]) -> bool:
diff --git a/products/replay_vision/backend/migrations/0146_replay_scanner_filter_error.py b/products/replay_vision/backend/migrations/0146_replay_scanner_filter_error.py
new file mode 100644
index 000000000000..d260f016665b
--- /dev/null
+++ b/products/replay_vision/backend/migrations/0146_replay_scanner_filter_error.py
@@ -0,0 +1,30 @@
+# Generated by Django 6.1.2 on 2026-10-30 21:00
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("replay_vision", "0145_replay_highlight_entry_person_key"),
+ ]
+
+ operations = [
+ migrations.AddField(
+ model_name="replayscanner",
+ name="filter_error",
+ field=models.TextField(
+ blank=True,
+ help_text="Why the scanner's recording filter cannot run, from the last sweep or estimate that tried it. Cleared when the filter changes or a sweep runs it.",
+ null=True,
+ ),
+ ),
+ migrations.AddField(
+ model_name="replayscanner",
+ name="filter_error_at",
+ field=models.DateTimeField(
+ blank=True,
+ help_text="When the filter error was recorded. Sweeps skip the scanner until it is a few hours old, then try the filter again.",
+ null=True,
+ ),
+ ),
+ ]
diff --git a/products/replay_vision/backend/migrations/max_migration.txt b/products/replay_vision/backend/migrations/max_migration.txt
index 7fe38d2410cf..6f3abfa04d5e 100644
--- a/products/replay_vision/backend/migrations/max_migration.txt
+++ b/products/replay_vision/backend/migrations/max_migration.txt
@@ -1 +1 @@
-0145_replay_highlight_entry_person_key
+0146_replay_scanner_filter_error
diff --git a/products/replay_vision/backend/models/replay_scanner.py b/products/replay_vision/backend/models/replay_scanner.py
index 58eb575c4fad..bfca710cdce4 100644
--- a/products/replay_vision/backend/models/replay_scanner.py
+++ b/products/replay_vision/backend/models/replay_scanner.py
@@ -282,6 +282,16 @@ class ReplayScanner(Taggable, ModelActivityMixin, UUIDModel):
blank=True,
help_text="When an estimate was last attempted, success or failure. Backs off the refresher on scanners whose estimate query keeps failing.",
)
+ filter_error = models.TextField(
+ null=True,
+ blank=True,
+ help_text="Why the scanner's recording filter cannot run, from the last sweep or estimate that tried it. Cleared when the filter changes or a sweep runs it.",
+ )
+ filter_error_at = models.DateTimeField(
+ null=True,
+ blank=True,
+ help_text="When the filter error was recorded. Sweeps skip the scanner until it is a few hours old, then try the filter again.",
+ )
# Written with the prompt by every path that sets one, see `prompt_questions`; inline scanners keep only a
# built-in scan's question. Not version-tracked: it restates the prompt and changes nothing about how the scanner scans.
@@ -427,6 +437,8 @@ class ReplayScanner(Taggable, ModelActivityMixin, UUIDModel):
# Written by sweeps and the read meter through queryset updates; a stale full save must not clobber them.
_MACHINE_OWNED_FIELDS = (
"estimate_attempted_at",
+ "filter_error",
+ "filter_error_at",
"last_swept_at",
"last_seen_session_id",
"deep_swept_through",
@@ -485,7 +497,12 @@ class ReplayScanner(Taggable, ModelActivityMixin, UUIDModel):
# A config edit must not wait out a backoff the old config earned.
self.estimated_at = None
self.estimate_attempted_at = None
- extra_fields.extend(["estimated_at", "estimate_attempted_at"])
+ # The filter changed, so the old filter's error no longer applies.
+ self.filter_error = None
+ self.filter_error_at = None
+ extra_fields.extend(
+ ["estimated_at", "estimate_attempted_at", "filter_error", "filter_error_at"]
+ )
if track_enabled and not old.enabled and self.enabled:
# Re-enabling restarts the sweep from now — don't backfill (and bill) the disabled gap.
self.last_swept_at = initial_watermark()
diff --git a/products/replay_vision/backend/queries/filter_errors.py b/products/replay_vision/backend/queries/filter_errors.py
new file mode 100644
index 000000000000..2abf4555e926
--- /dev/null
+++ b/products/replay_vision/backend/queries/filter_errors.py
@@ -0,0 +1,72 @@
+"""A scanner's recording filter that cannot run: telling it apart from a transient failure, and recording it."""
+
+import datetime as dt
+
+from django.utils import timezone
+
+import structlog
+
+from posthog.hogql.errors import ExposedHogQLError, TableAccessDeniedError
+
+from posthog.errors import ExposedCHQueryError, QueryErrorCategory, classify_query_error
+
+from products.replay_vision.backend.models.replay_scanner import ReplayScanner
+
+logger = structlog.get_logger(__name__)
+
+# A filter error usually needs a person to edit the filter, but our own query building can be the
+# cause too, so the sweep tries the filter again after this long rather than never.
+FILTER_ERROR_RECHECK = dt.timedelta(hours=6)
+
+# UNKNOWN_IDENTIFIER and UNKNOWN_TABLE are user-safe but come as often from our own query building
+# or a half-applied schema change, so they must not pause every scanner.
+_NOT_FILTER_CODES = frozenset({47, 60})
+
+_MAX_MESSAGE_LENGTH = 1000
+
+# Shown in place of the reason to a viewer who cannot access the scanner's targeted experiment.
+REDACTED_FILTER_ERROR = "The filter cannot run."
+
+
+def filter_error_message(error: BaseException) -> str | None:
+ """The user-facing reason the filter cannot run, or None when the error is not about the filter."""
+ if isinstance(error, TableAccessDeniedError):
+ return None
+ # Rate limits and timeouts are user-safe too, so the category keeps them out.
+ if isinstance(error, ExposedHogQLError) or (
+ isinstance(error, ExposedCHQueryError)
+ and error.code not in _NOT_FILTER_CODES
+ and classify_query_error(error) == QueryErrorCategory.USER_ERROR
+ ):
+ return str(error)[:_MAX_MESSAGE_LENGTH] or REDACTED_FILTER_ERROR
+ return None
+
+
+def filter_error_pending(scanner: ReplayScanner, now: dt.datetime | None = None) -> bool:
+ """Whether the scanner's filter failed recently enough that a sweep should not try it yet."""
+ if scanner.filter_error_at is None:
+ return False
+ return (now or timezone.now()) - scanner.filter_error_at < FILTER_ERROR_RECHECK
+
+
+def record_filter_error(scanner: ReplayScanner, message: str) -> None:
+ now = timezone.now()
+ # Matched on the version the failing run read, so a filter edited meanwhile is not marked broken.
+ ReplayScanner.all_origins.filter(pk=scanner.pk, scanner_version=scanner.scanner_version).update(
+ filter_error=message, filter_error_at=now
+ )
+ scanner.filter_error = message
+ scanner.filter_error_at = now
+ logger.warning(
+ "replay_vision.scanner_filter_error", scanner_id=str(scanner.id), team_id=scanner.team_id, reason=message
+ )
+
+
+def clear_filter_error(scanner: ReplayScanner) -> None:
+ if scanner.filter_error_at is None:
+ return
+ ReplayScanner.all_origins.filter(pk=scanner.pk, scanner_version=scanner.scanner_version).update(
+ filter_error=None, filter_error_at=None
+ )
+ scanner.filter_error = None
+ scanner.filter_error_at = None
diff --git a/products/replay_vision/backend/temporal/activities/find_scanner_candidates.py b/products/replay_vision/backend/temporal/activities/find_scanner_candidates.py
index 8c5c804ec324..c54bfd20ecff 100644
--- a/products/replay_vision/backend/temporal/activities/find_scanner_candidates.py
+++ b/products/replay_vision/backend/temporal/activities/find_scanner_candidates.py
@@ -25,6 +25,12 @@ from products.replay_vision.backend.models.replay_scanner import (
initial_watermark,
)
from products.replay_vision.backend.queries import excluded_sessions
+from products.replay_vision.backend.queries.filter_errors import (
+ clear_filter_error,
+ filter_error_message,
+ filter_error_pending,
+ record_filter_error,
+)
from products.replay_vision.backend.queries.scanner_candidate_query import (
DEEP_SWEEP_CANDIDATE_QUERY_TYPE,
DEFAULT_CANDIDATE_LIMIT,
@@ -140,6 +146,18 @@ def _seconds_left(started_at: float) -> float:
return FIND_SCANNER_CANDIDATES_TIMEOUT.total_seconds() - (time.monotonic() - started_at)
+def _fail_on_filter_error(scanner: ReplayScanner, error: Exception) -> None:
+ """Record a filter that cannot run and fail without retries, which only repeat the rejected query."""
+ message = filter_error_message(error)
+ if message is None:
+ return
+ record_filter_error(scanner, message)
+ record_sweep_outcome("filter_error")
+ raise ApplicationError(
+ f"ReplayScanner {scanner.id} has a filter that cannot run: {message}", non_retryable=True
+ ) from error
+
+
@activity.defn
@track_activity()
def find_scanner_candidates_activity(inputs: FindScannerCandidatesInputs) -> FindScannerCandidatesOutput:
@@ -202,9 +220,16 @@ def find_scanner_candidates_activity(inputs: FindScannerCandidatesInputs) -> Fin
record_sweep_outcome("no_principal")
return FindScannerCandidatesOutput(candidates=[], saturated=False)
+ if filter_error_pending(scanner):
+ # The filter failed recently and fails the same way until someone edits it, so skip the
+ # query. The watermark holds, like any other skipped tick.
+ record_sweep_outcome("filter_error")
+ return FindScannerCandidatesOutput(candidates=[], saturated=False)
+
try:
query = scanner.targeted_recordings_query()
except ValidationError as exc:
+ record_filter_error(scanner, "The filter is malformed and cannot be read.")
raise ApplicationError(
f"ReplayScanner {inputs.scanner_id} has malformed query: {exc}", non_retryable=True
) from exc
@@ -256,20 +281,29 @@ def find_scanner_candidates_activity(inputs: FindScannerCandidatesInputs) -> Fin
# tick (no watermark advance) instead of failing it on every fire.
record_sweep_outcome("experiment_linkage_unresolved")
return FindScannerCandidatesOutput(candidates=[], saturated=False)
+ except Exception as exc:
+ _fail_on_filter_error(scanner, exc)
+ raise
fetched = batch.matched
if batch.saturated:
record_candidate_page_full()
# Deliberately not wrapped: the in-query blocklists are off, so a swallowed failure here would
# dispatch the batch unfiltered. Returns empty when the scanner excludes nothing.
- excluded = excluded_sessions.excluded_session_ids(
- query_type=EXCLUDED_SESSIONS_QUERY_TYPE,
- team=scanner.team,
- candidate_query=candidate_query,
- candidates=fetched,
- scanner_id=str(scanner.id),
- seconds_remaining=_seconds_left(started_at),
- )
+ try:
+ excluded = excluded_sessions.excluded_session_ids(
+ query_type=EXCLUDED_SESSIONS_QUERY_TYPE,
+ team=scanner.team,
+ candidate_query=candidate_query,
+ candidates=fetched,
+ scanner_id=str(scanner.id),
+ seconds_remaining=_seconds_left(started_at),
+ )
+ except Exception as exc:
+ # A broken negative filter only fails here, since the fast query leaves the blocklists out.
+ _fail_on_filter_error(scanner, exc)
+ raise
+ clear_filter_error(scanner)
candidates = [c for c in fetched if c.session_id not in excluded]
# Deep candidates dispatch alongside fast ones, so the two share one in-flight budget: the deep
diff --git a/products/replay_vision/backend/temporal/activities/refresh_scanner_estimate.py b/products/replay_vision/backend/temporal/activities/refresh_scanner_estimate.py
index 90a495c114a1..96f2af5738ff 100644
--- a/products/replay_vision/backend/temporal/activities/refresh_scanner_estimate.py
+++ b/products/replay_vision/backend/temporal/activities/refresh_scanner_estimate.py
@@ -14,6 +14,7 @@ from products.replay_vision.backend.queries import (
is_experiment_linkage_unresolved,
refresh_scanner_estimate,
)
+from products.replay_vision.backend.queries.filter_errors import filter_error_message, filter_error_pending
from products.replay_vision.backend.temporal.decorators import track_activity
from products.replay_vision.backend.temporal.estimates_types import RefreshScannerEstimateInputs
from products.replay_vision.backend.temporal.metrics import record_estimate_outcome
@@ -28,6 +29,11 @@ def refresh_scanner_estimate_activity(inputs: RefreshScannerEstimateInputs) -> b
return False
if scanner.estimated_at is not None and timezone.now() - scanner.estimated_at < ESTIMATE_STALE_AFTER:
return False
+ if filter_error_pending(scanner):
+ # Stamped like a failed attempt, so the stale-estimate batch stops picking this scanner first.
+ ReplayScanner.objects.filter(pk=scanner.pk).update(estimate_attempted_at=timezone.now())
+ record_estimate_outcome("filter_error")
+ return False
try:
refresh_scanner_estimate(scanner, ch_user=ClickHouseUser.REPLAY_VISION)
except (DRFValidationError, PermissionDenied) as error:
@@ -46,5 +52,16 @@ def refresh_scanner_estimate_activity(inputs: RefreshScannerEstimateInputs) -> b
extra={"scanner_id": str(scanner.id), "reason": error.detail},
)
return False
+ except Exception as error:
+ message = filter_error_message(error)
+ if message is None:
+ raise
+ # The filter needs an edit, which a retry cannot make. The sweep records it on the scanner,
+ # since the estimate's wider query can fail where the sweep's does not.
+ record_estimate_outcome("filter_error")
+ activity.logger.warning(
+ "replay_vision.estimate_filter_error", extra={"scanner_id": str(scanner.id), "reason": message}
+ )
+ return False
record_estimate_outcome("refreshed")
return True
diff --git a/products/replay_vision/backend/tests/test_sweep.py b/products/replay_vision/backend/tests/test_sweep.py
index 9bdb3c72fb3d..ce88f132854a 100644
--- a/products/replay_vision/backend/tests/test_sweep.py
+++ b/products/replay_vision/backend/tests/test_sweep.py
@@ -9,9 +9,13 @@ from unittest.mock import MagicMock, patch
from django.utils import timezone
+from clickhouse_driver.errors import ServerException
from parameterized import parameterized
from temporalio.exceptions import ApplicationError, WorkflowAlreadyStartedError
+from posthog.hogql.errors import QueryError
+
+from posthog.errors import wrap_clickhouse_query_error
from posthog.models import Organization, Team, User
from posthog.redis import get_client
from posthog.temporal.session_replay.rasterize_recording.activities.stuck_counter import (
@@ -34,6 +38,7 @@ from products.replay_vision.backend.models.replay_scanner import (
)
from products.replay_vision.backend.models.replay_scanner_backfill import ReplayScannerBackfill
from products.replay_vision.backend.queries import excluded_sessions
+from products.replay_vision.backend.queries.filter_errors import FILTER_ERROR_RECHECK, filter_error_message
from products.replay_vision.backend.queries.scanner_candidate_query import (
DEFAULT_CANDIDATE_LIMIT,
SWEEP_EVENTS_LOOKBACK,
@@ -909,22 +914,32 @@ class TestFindScannerCandidatesActivity:
assert result.keyset_session_id == "blocked"
assert result.keyset_end == fetched[0].session_end
- def test_exclusion_failure_fails_the_tick_rather_than_dispatching(self) -> None:
+ @parameterized.expand(
+ [
+ ("transient", RuntimeError("clickhouse down"), RuntimeError),
+ ("broken_negative_filter", QueryError("Unable to resolve field: event"), ApplicationError),
+ ]
+ )
+ def test_exclusion_failure_fails_the_tick_rather_than_dispatching(
+ self, _name: str, error: Exception, raised: type[Exception]
+ ) -> None:
# The in-query blocklists are off by this point, so swallowing this would dispatch unfiltered.
scanner = _make_scanner(query=self._NEGATIVE_QUERY)
with (
patch(f"{_ACTIVITY}.ScannerCandidateQuery") as MockQuery,
- patch.object(excluded_sessions, "excluded_session_ids", side_effect=RuntimeError("clickhouse down")),
+ patch.object(excluded_sessions, "excluded_session_ids", side_effect=error),
):
_wire_batch(MockQuery)
MockQuery.return_value.run.return_value = [
CandidateSession(session_id="sess-a", session_end=dt.datetime(2026, 5, 1, 10, 0, tzinfo=dt.UTC))
]
- with pytest.raises(RuntimeError):
+ with pytest.raises(raised):
find_scanner_candidates_activity(
FindScannerCandidatesInputs(scanner_id=scanner.id, team_id=scanner.team_id)
)
+ scanner.refresh_from_db()
+ assert (scanner.filter_error is not None) is (raised is ApplicationError)
def test_raises_non_retryable_on_malformed_query(self) -> None:
scanner = _make_scanner()
@@ -939,6 +954,53 @@ class TestFindScannerCandidatesActivity:
)
assert exc_info.value.non_retryable is True
+ @parameterized.expand(
+ [
+ ("hogql", QueryError("Unable to resolve field: event"), True),
+ ("regex", wrap_clickhouse_query_error(ServerException("bad regexp", code=427)), True),
+ ("too_many_queries", wrap_clickhouse_query_error(ServerException("busy", code=202)), False),
+ ("timeout", wrap_clickhouse_query_error(ServerException("slow", code=159)), False),
+ ("unknown_identifier", wrap_clickhouse_query_error(ServerException("missing", code=47)), False),
+ ]
+ )
+ def test_a_filter_that_cannot_run_is_recorded_and_skipped_until_the_recheck(
+ self, _name: str, error: Exception, is_filter_error: bool
+ ) -> None:
+ scanner = _make_scanner()
+ inputs = FindScannerCandidatesInputs(scanner_id=scanner.id, team_id=scanner.team_id)
+ with _patched_queries() as (fast_query, _):
+ fast_query.return_value.run_batch.side_effect = error
+ with pytest.raises(ApplicationError if is_filter_error else type(error)) as exc_info:
+ find_scanner_candidates_activity(inputs)
+ scanner.refresh_from_db()
+ if not is_filter_error:
+ assert scanner.filter_error is None
+ return
+ assert isinstance(exc_info.value, ApplicationError) and exc_info.value.non_retryable is True
+ assert scanner.filter_error == filter_error_message(error)
+
+ fast_query.reset_mock()
+ find_scanner_candidates_activity(inputs)
+ assert not fast_query.return_value.run_batch.called
+
+ ReplayScanner.objects.filter(pk=scanner.pk).update(
+ filter_error_at=timezone.now() - FILTER_ERROR_RECHECK - dt.timedelta(minutes=1)
+ )
+ _wire_batch(fast_query)
+ find_scanner_candidates_activity(inputs)
+ assert fast_query.return_value.run_batch.called
+ scanner.refresh_from_db()
+ assert scanner.filter_error is None
+
+ def test_editing_the_filter_clears_its_error(self) -> None:
+ scanner = _make_scanner()
+ ReplayScanner.objects.filter(pk=scanner.pk).update(filter_error="broken", filter_error_at=timezone.now())
+ scanner.refresh_from_db()
+ scanner.query = {"kind": "RecordingsQuery", "filter_test_accounts": True}
+ scanner.save()
+ scanner.refresh_from_db()
+ assert scanner.filter_error is None and scanner.filter_error_at is None
+
def test_priming_pass_runs_once_for_a_never_swept_scanner(self) -> None:
scanner = _make_scanner(primed_at=None)
primed = [
diff --git a/products/replay_vision/frontend/generated/api.schemas.ts b/products/replay_vision/frontend/generated/api.schemas.ts
index 3efb3b28feca..fdc84efffe18 100644
--- a/products/replay_vision/frontend/generated/api.schemas.ts
+++ b/products/replay_vision/frontend/generated/api.schemas.ts
@@ -1368,6 +1368,11 @@ export interface ReplayScannerApi {
readonly dashboard_suggested: boolean
/** Watermark for the scanner's last scheduled fire. Mirrors Temporal schedule state for recovery. */
readonly last_swept_at: string
+ /**
+ * Why the scanner's recording filter cannot run, from the last sweep or estimate that tried it. Cleared when the filter changes or a sweep runs it.
+ * @nullable
+ */
+ readonly filter_error: string | null
readonly created_at: string
/** User who created the scanner. */
readonly created_by: UserBasicApi | null
@@ -1512,6 +1517,11 @@ export interface PatchedReplayScannerApi {
readonly dashboard_suggested?: boolean
/** Watermark for the scanner's last scheduled fire. Mirrors Temporal schedule state for recovery. */
readonly last_swept_at?: string
+ /**
+ * Why the scanner's recording filter cannot run, from the last sweep or estimate that tried it. Cleared when the filter changes or a sweep runs it.
+ * @nullable
+ */
+ readonly filter_error?: string | null
readonly created_at?: string
/** User who created the scanner. */
readonly created_by?: UserBasicApi | null
diff --git a/products/replay_vision/frontend/replay_scanners/components/ScannerStatusLabel.tsx b/products/replay_vision/frontend/replay_scanners/components/ScannerStatusLabel.tsx
index 690e525919a7..02de305af67f 100644
--- a/products/replay_vision/frontend/replay_scanners/components/ScannerStatusLabel.tsx
+++ b/products/replay_vision/frontend/replay_scanners/components/ScannerStatusLabel.tsx
@@ -17,6 +17,7 @@ const STATUS_LABEL: Record<ScannerStatus['kind'], { label: string; tone: StatusT
off: { label: 'Off', tone: 'muted' },
limit_reached: { label: 'Stopped', tone: 'danger' },
quota_exhausted: { label: 'Stopped', tone: 'danger' },
+ filter_error: { label: 'Filter error', tone: 'danger' },
starting: { label: 'Starting', tone: 'warning' },
delayed: { label: 'Delayed', tone: 'warning' },
no_matches: { label: 'No matches', tone: 'warning' },
diff --git a/products/replay_vision/frontend/replay_scanners/components/ScannerStatusStrip.tsx b/products/replay_vision/frontend/replay_scanners/components/ScannerStatusStrip.tsx
index 3a01a0c56599..ce1d795e8543 100644
--- a/products/replay_vision/frontend/replay_scanners/components/ScannerStatusStrip.tsx
+++ b/products/replay_vision/frontend/replay_scanners/components/ScannerStatusStrip.tsx
@@ -42,6 +42,8 @@ function statusDetail(status: ScannerStatus, resetsOn: string | null, periodEnds
: limitReachedTooltip(status)
case 'quota_exhausted':
return `Your organization's Replay Vision credits are used up${resetsOn ? ` until ${resetsOn}` : ''}.`
+ case 'filter_error':
+ return `The filters can't run, so no new recordings are scanned. ${status.message}`
case 'starting':
return 'The first scan is running. Results usually appear within 15 minutes.'
case 'delayed':
@@ -133,14 +135,14 @@ export function ScannerStatusStrip({ scannerId }: { scannerId: string }): JSX.El
Your organization's spend limit is used up too, so raise it in billing as well.
</span>
)}
- {status.kind === 'no_matches' && (
+ {(status.kind === 'no_matches' || status.kind === 'filter_error') && (
<>
{' '}
<Link
to={urls.replayVisionScannerTriggers(scannerId)}
data-attr="vision-scanner-status-review-filters"
>
- Review filters
+ {status.kind === 'filter_error' ? 'Edit filters' : 'Review filters'}
</Link>
</>
)}
diff --git a/products/replay_vision/frontend/replay_scanners/newScanner.ts b/products/replay_vision/frontend/replay_scanners/newScanner.ts
index e3696dbb62da..423b3fbf38a4 100644
--- a/products/replay_vision/frontend/replay_scanners/newScanner.ts
+++ b/products/replay_vision/frontend/replay_scanners/newScanner.ts
@@ -45,6 +45,7 @@ export function newScanner(teamName?: string | null): ScannerFormValues {
sweep_throttle_factor: 1,
dashboard_id: null,
dashboard_suggested: false,
+ filter_error: null,
} as const
return {
diff --git a/products/replay_vision/frontend/replay_scanners/scannerStatus.test.ts b/products/replay_vision/frontend/replay_scanners/scannerStatus.test.ts
index 723b18b53fe4..6f1e46d7b7ad 100644
--- a/products/replay_vision/frontend/replay_scanners/scannerStatus.test.ts
+++ b/products/replay_vision/frontend/replay_scanners/scannerStatus.test.ts
@@ -16,6 +16,7 @@ const HEALTHY: ScannerStatusFields = {
sweep_throttle_factor: 1,
created_at: '2026-05-01T00:00:00Z',
last_swept_at: NOW.subtract(40, 'minute').toISOString(),
+ filter_error: null,
}
const DROUGHT = { everScanned: true, samplingRate: 1 }
@@ -38,6 +39,12 @@ describe('scannerStatus', () => {
'limit_reached',
],
['stopped when the org quota is used up', {}, { quotaExhausted: true }, 'quota_exhausted'],
+ [
+ 'filter error ahead of the delay it causes',
+ { filter_error: 'Unable to resolve field: event', last_swept_at: NOW.subtract(3, 'hour').toISOString() },
+ {},
+ 'filter_error',
+ ],
['starting while the first sweep has not finished', createdMinutesAgo(10), {}, 'starting'],
['delayed once a first sweep is over an hour late', createdMinutesAgo(70), {}, 'delayed'],
[
diff --git a/products/replay_vision/frontend/replay_scanners/scannerStatus.ts b/products/replay_vision/frontend/replay_scanners/scannerStatus.ts
index b22fe93c4835..6eb3cbea7d28 100644
--- a/products/replay_vision/frontend/replay_scanners/scannerStatus.ts
+++ b/products/replay_vision/frontend/replay_scanners/scannerStatus.ts
@@ -16,6 +16,7 @@ export type ScannerStatus =
| { kind: 'off'; reason: 'disabled' | 'no_sampling' }
| { kind: 'limit_reached'; free_only: boolean; credit_limit: number | null; limit_from_free_credits: boolean }
| { kind: 'quota_exhausted' }
+ | { kind: 'filter_error'; message: string }
| { kind: 'starting' }
| { kind: 'delayed'; lastCheckedAt: Dayjs }
| { kind: 'no_matches'; drought: ScanDrought }
@@ -33,6 +34,7 @@ export type ScannerStatusFields = Pick<
| 'sweep_throttle_factor'
| 'created_at'
| 'last_swept_at'
+ | 'filter_error'
>
/** The one status the scanner page leads with. Earlier checks win, so a scanner that is off never also reads as stopped. */
@@ -58,6 +60,9 @@ export function scannerStatus(
if (options.quotaExhausted) {
return { kind: 'quota_exhausted' }
}
+ if (scanner.filter_error) {
+ return { kind: 'filter_error', message: scanner.filter_error }
+ }
const factor = Math.max(1, scanner.sweep_throttle_factor)
const intervalMinutes = SWEEP_INTERVAL_MINUTES * factor
const createdAt = dayjs(scanner.created_at)
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index f8001052d36e..1622b39e95ce 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -79613,6 +79613,11 @@ export namespace Schemas {
readonly dashboard_suggested: boolean;
/** Watermark for the scanner's last scheduled fire. Mirrors Temporal schedule state for recovery. */
readonly last_swept_at: string;
+ /**
+ * Why the scanner's recording filter cannot run, from the last sweep or estimate that tried it. Cleared when the filter changes or a sweep runs it.
+ * @nullable
+ */
+ readonly filter_error: string | null;
readonly created_at: string;
/** User who created the scanner. */
readonly created_by: UserBasic | null;
@@ -92505,6 +92510,11 @@ export namespace Schemas {
readonly dashboard_suggested?: boolean;
/** Watermark for the scanner's last scheduled fire. Mirrors Temporal schedule state for recovery. */
readonly last_swept_at?: string;
+ /**
+ * Why the scanner's recording filter cannot run, from the last sweep or estimate that tried it. Cleared when the filter changes or a sweep runs it.
+ * @nullable
+ */
+ readonly filter_error?: string | null;
readonly created_at?: string;
/** User who created the scanner. */
readonly created_by?: UserBasic | null;