BrowserStack Screenshots Not Capturing Web Fonts Correctly
Diagnose missing or incorrect fonts in BrowserStack screenshots by checking the capture product, font requests, CSS face selection, and capture timing.
BrowserStack Screenshots not capturing web fonts correctly? First identify which BrowserStack product took the screenshot, then check whether that remote browser could fetch the intended font and whether capture waited for the page to settle. A fallback or incorrect face can result from a failed or restricted font request, a CSS family or weight mismatch, browser-specific rendering, or capture happening too early. The title alone does not establish a BrowserStack defect, and adding a delay will not fix a font the browser cannot load.
Use the workflow below to narrow the cause. The relevant controls differ between BrowserStack Screenshots API, Percy, BrowserStack Live, and screenshots triggered by Selenium or another browser automation driver.
1. Identify which BrowserStack screenshot flow you use
Before changing waits or configuration, record the capture product and reproduce the issue with a consistent setup. BrowserStack’s Screenshots API documents its own browser, OS, and wait_time options; Percy has separate snapshot waits and asset diagnostics. Do not assume one product’s settings apply to another. BrowserStack Screenshots API documentation · Percy troubleshooting
| Capture flow | Where to investigate | Relevant wait approach |
|---|---|---|
| BrowserStack Screenshots API | API parameters, selected browser and OS, and the resulting screenshot | Documented fixed wait_time |
| Percy | Build/CI logs, failed asset requests, Percy snapshot setup | Script-based waits such as waitForSelector or waitForTimeout |
| BrowserStack Live | Remote browser developer tools and network behavior, when available | Wait for the page and font to load before capturing manually |
| Selenium or another driver | Driver logs, browser network/console data, page state | Wait on a specific page condition; use the Font Loading API where page script execution is available |
Keep a note of the product, browser and version, operating system, viewport, URL, font family and weight, and whether the failure occurs on every run or only on one browser/OS combination. For comparisons, hold the URL, viewport, page state, and wait constant while changing one browser or OS variable.
2. Check whether the remote browser fetched the font
A page can load while its font file fails. Inspect the remote browser’s network requests, Percy build or CI logs, or browser developer tools when available. Find the request for the expected font asset, then check:
- Whether the request was made and completed successfully.
- The requested URL, response status or network error, redirects, and response access restrictions.
- Whether authorization, host allowlisting, or another network policy blocks the request.
- Whether the stylesheet or font file is served from a public host or a private/staging host.
- Whether lazy loading means the relevant stylesheet or content is requested only after scrolling or another page action.
Percy’s troubleshooting guidance calls out failed font and CSS assets, network errors, host allowlisting, timeouts, and lazy loading. Treat those checks as Percy guidance; the separate Screenshots API and Live flows have their own available diagnostics. If a font host is private, verify that the BrowserStack Local connection and routing can reach both the page and the font host. BrowserStack describes Local as a tunnel for remote browsers to access local and private resources. Percy asset troubleshooting · BrowserStack Local overview
A successful page request does not prove that a separate font host is reachable. A failed or blocked font request is a plausible cause to investigate, not something established by the title alone.
3. Verify the CSS face the text actually requests
If the font request succeeded, check whether the page applies the face you expect. Inspect the loaded stylesheet and the computed style of representative text. Compare the declared @font-face family, source URL, weight, and style with the family, weight, and style requested by the element.
/* Example: declarations and use should agree on family and weight. */
@font-face {
font-family: "Product Sans";
src: url("/fonts/product-sans-regular.woff2") format("woff2");
font-weight: 400;
font-style: normal;
}
.heading {
font-family: "Product Sans", sans-serif;
font-weight: 400;
}This is an illustrative configuration, not a claim about your site’s stylesheet. Check the actual CSS and the actual requested file. A page that asks for weight 600 while only a regular face is declared may use a synthesized or fallback appearance. Also check for a family-name typo, unexpected stylesheet override, incorrect src, or a representative glyph missing from the chosen font. Do not attribute a CSS mismatch to BrowserStack without evidence from the page.
4. Wait for the right readiness condition
BrowserStack Screenshots API
The Screenshots API documentation lists wait_time with a default of 5 seconds and supported values of 2, 5, 10, 15, 20, or 60 seconds. This is a fixed delay, not confirmation that every font has loaded. Try a longer supported value as a diagnostic if the page needs more time, then inspect the font request if the result is still wrong. Check the current API documentation for parameter syntax and availability. Screenshots API parameters
Percy script-based snapshots
Wait for the relevant element or use the documented timeout controls, such as waitForSelector or waitForTimeout, before taking a snapshot. A selector wait confirms that the element is present; it does not by itself establish that the intended font request succeeded. If the face remains wrong, inspect the asset and network diagnostics. Percy snapshot and asset troubleshooting
Custom browser automation
When page JavaScript can run in the browser, the Font Loading API provides a readiness signal for the document’s font set:
// Run in the page context after navigation, before taking the screenshot.
await document.fonts.ready;
const heading = document.querySelector("h1");
const headingStyle = getComputedStyle(heading);
console.log({
family: headingStyle.fontFamily,
weight: headingStyle.fontWeight,
requestedFaceAvailable: document.fonts.check(
`${headingStyle.fontWeight} 16px "Product Sans"`
)
});document.fonts.ready resolves when the document’s font loading and related layout work have settled. document.fonts.check() can help check whether a font is available for a requested description. Neither proves that the page used the intended face for every glyph, so also verify the request and computed style. These are browser APIs, not BrowserStack-specific settings. MDN: FontFaceSet.ready · MDN: FontFaceSet.check()
5. Compare runs and collect evidence before escalating
- Reproduce the capture and save the screenshot plus the exact capture configuration.
- Record the product flow, browser/version, OS, viewport, URL, and page state.
- Save relevant font request outcomes, console or CI errors, and the computed family and weight for affected text.
- Compare a working and failing browser/OS combination while holding the page, viewport, and readiness wait constant.
- Repeat intermittent failures and retain each run’s evidence. If the problem remains browser- or width-specific, include that pattern when contacting support.
Percy’s troubleshooting material recommends retries for one-off resource issues and investigation of persistent browser- or width-specific failures. Repeating a run can reveal intermittency, but it does not explain a consistently blocked font request. Percy troubleshooting guidance
BrowserStack Screenshots API example
For the Screenshots API flow, use its documented API configuration and choose an appropriate supported wait. The following cURL example shows the structure for making a URL screenshot request; consult the linked documentation for the exact endpoint, authentication, and parameter syntax for your account and current API version.
# Illustrative request structure; confirm endpoint and parameters in current docs.
curl -G "BROWSERSTACK_SCREENSHOTS_API_ENDPOINT" \
--data-urlencode "url=https://example.com" \
--data-urlencode "wait_time=10" \
--data-urlencode "browser=chrome" \
--data-urlencode "os=Windows" \
-o screenshot.pngThe endpoint and browser/OS parameter values are placeholders here because they depend on the documented API configuration; do not submit this literal placeholder endpoint. The key point for this diagnosis is that increasing wait_time tests capture timing only. It cannot repair a blocked font host or a CSS face mismatch.
Common causes and fixes
| Symptom | Likely diagnostic branch | What to check or change |
|---|---|---|
| Text consistently appears in a fallback font | The desired font file did not load or the CSS did not select it | Inspect the font request, family name, weight/style declaration, and computed style. |
| Page loads, but font requests fail | Host, network, authorization, redirect, or allowlist issue | Inspect request status and errors; verify access to the font host. For private assets, check Local Testing routing. |
| Only some weights look wrong | Requested weight/style does not match a declared face or available file | Compare the element’s computed weight/style with the actual @font-face declarations and files. |
| Screenshot is wrong only on some runs | Timing or intermittent resource availability | Capture request logs across runs; wait for a relevant element or font readiness where supported, then investigate repeated failures. |
| One browser or OS differs | Browser-specific rendering or a browser-specific asset path/response | Compare request outcomes and computed styles with other combinations while keeping the capture state fixed. |
| Longer wait changes nothing | The problem may be asset access or CSS selection rather than timing | Inspect font requests and the selected family/weight instead of increasing the delay indefinitely. |
Performance, reliability, and cost considerations
Use the shortest wait or readiness condition that reliably captures the intended state. A fixed delay adds its duration to every capture, even when fonts load quickly, while a condition-based wait can target the page state you need when your capture flow supports it. A wait can reduce early captures but cannot make a failed request succeed. For intermittent failures, retain request and console evidence rather than relying only on retries.
The research material does not establish a price or billing behavior for BrowserStack captures, so check your current BrowserStack plan and product documentation for costs. If you switch capture services, compare the actual capture options, diagnostics, and billing terms you need instead of assuming they are equivalent.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. For example, request a screenshot directly from a URL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for parameters and formats. ScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Does the title prove BrowserStack has a font bug?
No. It does not identify the capture product, page, browser, font request, or CSS. Use the request and rendering checks above to establish what failed.
Will a 60-second wait always fix the screenshot?
No. The Screenshots API lists 60 seconds as a supported wait value, but a delay cannot fix an inaccessible font file or an incorrectly selected face.
Does document.fonts.ready confirm that my preferred font rendered?
It signals that the document’s font set has settled. Also check the intended font request and the computed family and weight on the affected text.
Should I use BrowserStack Local for every missing font?
Only investigate Local when the page or font resource is private or local and the remote browser needs tunnel access to it. Public asset failures require their own network and CSS diagnosis.
