diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx
index 4030f3ef..86331900 100644
--- a/self-host/customize-deployment/environment-variables.mdx
+++ b/self-host/customize-deployment/environment-variables.mdx
@@ -89,13 +89,18 @@ Variables that control the scheduler worker and background cleanup jobs.
 
 Configure the headless browser used for screenshots and PDF exports.
 
-| Variable                                  | Description                                                                                      |
-| :---------------------------------------- | :----------------------------------------------------------------------------------------------- |
-| `HEADLESS_BROWSER_HOST`                   | Hostname for the headless browser                                                                |
-| `HEADLESS_BROWSER_PORT`                   | Port for the headless browser (default=3001)                                                     |
-| `HEADLESS_BROWSER_MAX_SCREENSHOT_RETRIES` | Maximum number of times the scheduler retries a failed screenshot before giving up. (default=5)  |
-| `HEADLESS_BROWSER_RETRY_BASE_DELAY_MS`    | Base delay in milliseconds for exponential-backoff retries on failed screenshots. (default=3000) |
-| `USE_SECURE_BROWSER`                      | Use secure WebSocket connections for headless browser (default=false)                            |
+| Variable                                  | Description                                                                                                                                                                                                                                                             |
+| :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HEADLESS_BROWSER_HOST`                   | Hostname for the headless browser                                                                                                                                                                                                                                       |
+| `HEADLESS_BROWSER_PORT`                   | Port for the headless browser (default=3001)                                                                                                                                                                                                                            |
+| `HEADLESS_BROWSER_MAX_SCREENSHOT_RETRIES` | Maximum number of times the scheduler retries a failed screenshot before giving up. (default=5)                                                                                                                                                                         |
+| `HEADLESS_BROWSER_RETRY_BASE_DELAY_MS`    | Base delay in milliseconds for exponential-backoff retries on failed screenshots. (default=3000)                                                                                                                                                                        |
+| `HEADLESS_BROWSER_SCREENSHOT_TIMEOUT_MS`  | Maximum time in milliseconds Lightdash waits for a dashboard's tiles and charts to report ready before taking a screenshot. Also applies to per-element operations during capture. (default=180000). See note below if you raise this above the browser session limit.  |
+| `USE_SECURE_BROWSER`                      | Use secure WebSocket connections for headless browser (default=false)                                                                                                                                                                                                   |
+
+<Note>
+  The headless-browser container has its own session timeout (for example, browserless v2's `TIMEOUT`, which defaults to 30 seconds). That value must be greater than or equal to `HEADLESS_BROWSER_SCREENSHOT_TIMEOUT_MS`, otherwise the browser will terminate the session before Lightdash's readiness wait expires and the screenshot will fail. If you raise `HEADLESS_BROWSER_SCREENSHOT_TIMEOUT_MS` for dashboards that legitimately take longer than three minutes to render, raise the browser container's session timeout to match.
+</Note>
 
 ## Personal access tokens