Troubleshooting
The handful of things that trip people up, and how to fix each one.
Most of these come down to driving a real browser against Google, not a bug in the tool.
A CAPTCHA or consent page
Because gsearch automates a browser against Google, Google may show a consent
form or a CAPTCHA, especially the first time or from a fresh IP. This is the
expected friction, not a failure. The fix is the persistent profile: run once
with --no-headless so you can see the window, solve the challenge or accept
the consent form by hand, and the profile at ~/.cache/gsearch-profile
remembers the session. Later headless runs reuse it and go straight through.
gsearch search "epl" --no-headless
If a CAPTCHA keeps returning, your IP is being rate-limited. Slow down, leave it a while, and keep using the persistent profile so the solved session carries forward. gsearch is for personal, low-volume research; a gentle rate is what keeps it working.
"No Google Search content found"
The page loaded but the extractor found nothing to pull. Usually this means the
browser landed on a consent or CAPTCHA page rather than the results, so the DOM
had no result blocks. Run once with --no-headless to see what Chrome actually
rendered, clear any interstitial, and retry. Raising --timeout also helps if a
slow connection meant the results had not finished rendering when the extractor
ran.
"Browser not installed" or a launch error
patchright needs a Chrome or Chromium build to drive. If launching fails because none is present, install the private Chromium build:
make browser # from a source checkout
patchright install chromium # otherwise
If you would rather use an existing Google Chrome, gsearch can drive it through
the chrome channel; make sure Chrome is installed and up to date. See
installation.
Empty vertical results
A vertical (-v images, -v shopping, and so on) returned nothing under
vertical_results. Some queries have a thin or empty tab on Google itself, and
some vertical layouts vary by region. Try a broader query, confirm the same tab
has results in a normal browser, and run with --no-headless to watch what the
vertical page actually rendered. Note that the web feature blocks are not
populated in a non-web vertical; the data lives under vertical_results.
A slow first run
The first run after a fresh install is the slowest: Chrome is cold and the
profile is new. Later runs reuse the warm persistent profile and are quicker. If
runs are consistently slow, raise --timeout so the extractor waits long enough
for a heavy page, and check the response: NNNNms line in the summary to see
where the time is going.
Checking what happened
When a run behaves unexpectedly, --no-headless is the most useful tool: it
shows you exactly what Chrome loaded, which is almost always enough to tell a
CAPTCHA from a thin page from a slow render.