apache/superset · error · ReportScheduleScreenshotTimeout

A timeout occurred while taking a screenshot.

Error message

A timeout occurred while taking a screenshot.

What it means

ReportScheduleScreenshotTimeout: a celery SoftTimeLimitExceeded escaped the screenshot capture. For ReportScheduleType.REPORT the raw signal is re-raised (so terminal cleanup runs); for ALERTS that attach a screenshot it is converted to this typed timeout error with its established error-notification behavior.

Source

Thrown at superset/commands/report/execute.py:826

                datetime.now(timezone.utc).replace(tzinfo=None) - start_time
            ).total_seconds()
            logger.warning(
                "report_capture_terminal %s elapsed_seconds=%.2f "
                "remaining_seconds=%s terminal_reason=celery_soft_timeout",
                self._log_context,
                elapsed_seconds,
                (
                    f"{self._report_execution_context.deadline.remaining_seconds:.2f}"
                    if self._report_execution_context
                    else None
                ),
            )
            if self._report_schedule.type == ReportScheduleType.REPORT:
                raise
            # Alerts that attach a screenshot retain their established
            # format-specific timeout and error-notification behavior. Report
            # executions propagate the Celery signal to terminal cleanup.
            raise ReportScheduleScreenshotTimeout() from ex
        except ReportExecutionBudgetExceededError:
            raise
        except Exception as ex:
            elapsed_seconds = (
                datetime.now(timezone.utc).replace(tzinfo=None) - start_time
            ).total_seconds()
            logger.error(
                "report_capture_terminal %s elapsed_seconds=%.2f "
                "remaining_seconds=%s terminal_reason=%s",
                self._log_context,
                elapsed_seconds,
                (
                    f"{self._report_execution_context.deadline.remaining_seconds:.2f}"
                    if self._report_execution_context
                    else None
                ),
                type(ex).__name__,
            )

View on GitHub (pinned to f4587218dd)

Solutions

1. Raise the relevant time limit (Celery task_soft_time_limit / screenshot timeout config) for the reporting worker
2. Speed up the target: fewer charts, faster queries, caching enabled for the dashboard's charts
3. Disable force_screenshot or the screenshot attachment for that alert if the image is optional

Example fix

# before
CELERYD_TASK_SOFT_TIME_LIMIT = 120  # heavy dashboard times out

# after
CELERYD_TASK_SOFT_TIME_LIMIT = 600  # sized to slowest dashboard render

# estimate before scheduling: dashboard render must fit the soft time limit
assert slowest_chart_seconds * chart_count < celery_soft_time_limit * 0.8

try:
    _get_screenshots()
except ReportScheduleScreenshotTimeout:
    # alert-type schedule: notify + optionally retry once with lower load
    notify_timeout(report_schedule)

When it happens

Trigger: Screenshot capture exceeding the Celery soft time limit (task_soft_time_limit / screenshot task limits) during an alert execution with a screenshot attached; heavy dashboards with many charts or slow data sources.

Common situations: Dashboards whose charts query slow databases, so rendering exceeds the limit; lowering Celery soft time limits for safety; screenshots of tabbed dashboards multiplying capture time.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• A timeout occurred while generating a dataframe.
• Report schedule was modified or deleted by another process d
• Screenshot failed; aborting to avoid sending a partial repor
• Failed taking a screenshot {str(ex)}
• Report Schedule execution failed when generating a screensho

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/c85bcd7dff48d244. Report an issue: GitHub.