Repository navigation
the task only fails in headless
You watch it run, it works. You run it unattended, it fails. The conclusion everybody reaches first is that the site can tell it is headless, and that is the least likely of the six explanations below.
Work through them in this order, because the first three are free to check and account for most of it.
The commonest cause by a distance, and it has nothing to do with detection. A headed window is whatever size your screen made it; a headless one is whatever the default is. Different width means a different layout, and on a responsive site a different layout means different elements.
A navigation that is a row of links at 1600 pixels is a hamburger menu at 900. The selector the agent used when you watched does not exist in the other layout, and the failure reads as "element not found".
Check it by looking at what the run actually saw. The live view shows the whole window, per watching the agent work, and it works headless precisely because there is still a window being composited.
When you watch, you are slow. You read the page, you move the mouse, seconds pass, and the page finishes loading during them. Unattended, the calls arrive as fast as they can be issued and the race that you always won is now a coin flip.
This is the single biggest reason "it worked when I watched it" is not evidence that the task is correct. The mechanism, and the fix of waiting for a state rather than a duration, is in when the page changes under the AI agent.
A login that re-challenged, a code, a confirmation, a file to attach that the agent cannot attach. Watching, you supplied it without thinking of it as a step. Unattended, there is nobody.
This one is easy to miss precisely because it did not feel like part of the task. The check is to run headed and pay attention to everything you do with your own hands.
A print dialog, a file picker, a permission prompt, a basic-auth box. These are operating-system windows rather than parts of the page, so nothing that drives a page can dismiss them, and the run stalls until a timeout.
Headed, you close it in a second and forget it happened.
You watched with a profile that had cookies, consent choices and a login in it. The unattended run used a fresh one, so it got a consent wall, a locale picker, or a sign-in page where you got the content.
The tell is that the failure happens at the very first read rather than deep in the task. A persistent profile directory is what makes the two runs comparable, and it is set out on the MCP server page.
Last, not first, and when it happens it is usually not about headless as such: it is the rhythm of an unattended run, the absence of the pauses a person makes, or the volume of a loop. That family has its own pages: the timing signal AI agents give off and agent retry loops trip rate limits, not fingerprints.
Before concluding this, rule out the five above. They are cheaper to check and they are more often the answer.
Run the same task headed and headless, and compare the first read of each.
If the two reads differ, the cause is in 1, 5 or 6 and you can usually tell which by looking: a different layout is 1, a consent wall or a login is 5, a challenge page is 6. If the two reads match and the failure comes later, the cause is 2, 3 or 4, and the question becomes which step.
That is the same instrument as browser problem or model problem applied to a narrower question, and it is two runs.
Headless is the default and each launch decides for itself. A saved session does not record the mode, so a browser reopened by a headless server stays hidden even if it was headed last time you used it.
Worth knowing because it removes one possible explanation: a run is not accidentally inheriting a headed mode from yesterday. Whatever it is, it is one of the six.
Why does my agent work headed and fail headless? Most often a different window size producing a different layout, or a timing race that watching used to win. Site detection is the last thing to suspect, not the first.
Does headless change the page? Indirectly, through the viewport. A responsive site at a different width is a different document, with different elements.
Why does it work when I watch it? Because you are slow. Your reading time was the wait the task never declared.
Can the agent dismiss a print or file dialog? No. Those are operating-system windows, not parts of the page.
How do I tell which of the six it is? Run both modes and compare the very first read. Differing there points at the layout, the session or the site; matching there points at timing, a human step, or a dialog.
See also: watching the agent work, which shows the window the headless run actually has, and when the page changes under the AI agent for the timing half.
- The behaviour that a saved session does not record headless, so a browser reopened by a headless server stays hidden, is this project's own documented behaviour on the MCP server page.
- The ordering of the six causes is from experience with this browser rather than from a study, and the page is explicit that the popular explanation is the least likely one rather than claiming a measured frequency.
The order is the content. Everybody starts at six and the answer is almost always one or two.
- OpenAI Operator alternatives
- Open-source Operator-style agents
- Is OpenAI Operator still available?
- OpenAI Operator vs Claude computer use
- browser-use alternatives
- Choosing an AI browser agent
- Open-source AI browser agents
- Open-source computer-use agents
- What is an AI web agent?
- AI browser agents vs traditional scraping
- Cloud browser infrastructure for AI agents, explained
- Browserbase alternatives
- Firecrawl vs an AI browser agent
- Skyvern alternatives
- Stagehand vs browser-use
- Project Mariner is gone: what replaced it
- Manus alternatives
- Gemini computer use vs Claude computer use
- A stealth browser MCP, reviewed honestly by its own wiki
- AI browser vs AI browser agent: which one do you want?
- AI browser agent vs RPA: which one fits the job
- AI browser agent vs n8n, Zapier and Make
- Vercel agent-browser alternatives, compared honestly
- What is an agentic browser? Definition and the two kinds
- Open-source agentic browsers: the three layers, compared
- Choosing an MCP server for browser automation: four axes
- Stealth MCP servers compared: Camoufox, nodriver, Patchright
- Playwright MCP alternatives, and the three you don't need
- Autonomous browser agents: the four rungs of autonomy
- What is actually free in the AI browser agent stack
- browser-use on GitHub: what the repo actually gives you
- Playwright MCP vs Chrome DevTools MCP: different jobs
- How to choose among MCP servers: a map by category
- Which MCP servers are worth adding to Claude Code
- MCP on GitHub: finding servers and judging them fast
- MCP vs an API: the decision, and what the wrapper costs
- MCP alternatives: when the protocol is the wrong shape
- Why does my AI agent get blocked?
- The timing signal AI agents give off
- Agent retry loops trip rate limits, not fingerprints
- Claude computer use detected as a bot
- browser-use getting blocked: what you can and cannot change
- Playwright MCP session blocked: four causes, four fixes
- Playwright MCP and captchas: what actually gets you past
- Cloudflare and a browser MCP server: what is being read
- Can an AI agent solve a captcha? The honest answer
- Getting an AI agent to fill out forms
- The best model for an MCP browser agent, and what it really costs
- Browser problem or model problem?
- How to use a Playwright MCP server with Claude Code
- Extracting data to a CSV with an AI agent
- Monitoring a page for changes with an AI agent
- How to let Claude Desktop control a browser
- How to add a browser to Cursor as an MCP server
- Using an AI agent to hunt for apartments
- Getting website data into Google Sheets with an AI agent
- Using an AI agent to download invoices from portals
- AI agents for web research
- Using an AI agent to test your own website
- How to add a browser to Cline as an MCP server
- Posting to social media with an AI agent
- Posting to Facebook with an AI agent
- Posting to Instagram with an AI agent
- Posting to X with an AI agent
- Automating LinkedIn posts: read this first
- Appointment bots: what they are and what an agent can legitimately do
- Track prices across sites with an AI agent
- Build a lead list with an AI browser agent
- Run an AI browser agent on a schedule
- AI browser agent with a local LLM: what changes
- Should you log your AI agent into your accounts?
- How to write a task an AI browser agent can follow
- Move data between two web apps with an AI agent
- The MCP server
- How the tools are shaped, and why
- Playwright MCP vs the Playwright CLI: which fits when
- Playwright MCP: browser is already in use, and the fix
- Playwright MCP best practices: four decisions that matter
- Playwright MCP with a proxy, and the three leaks it leaves
- A browser MCP server in GitHub Copilot: setup and limits
- Using a browser MCP server for web scraping: the pattern
- Which LLM for browser automation: the four properties
- How to build a browser agent, and what to take instead
- Getting an AI agent to log into a website: three routes
- MCP tools, resources and prompts: who controls each
- How many MCP tools is too many? The context arithmetic
- How to build an MCP server: the decisions, not the scaffold
- Local or remote MCP server: what changes, and what does not
- Writing an MCP client in Python: the thirty-line version
- Self-hosted AI agent: what one actually costs to run
- How long an AI browser agent takes per step, measured
- Text, HTML, snapshot or screenshot: what the agent should read
- Giving an AI browser agent a stopping condition
- Keeping an AI browser agent out of destructive actions
- Why did the AI agent click the wrong thing
- When the page changes under the AI agent
- Running one AI agent task across a list of sites
- Seeing a page as it appears in another country
- Getting data out of a dashboard with no export button
- Two browsers in one session: main and support
- Finding the dead links on a site with an AI agent
- Filling a CRM record from a company's website
- One form submission per spreadsheet row, with an AI agent
- Dated screenshots of a page as evidence
- Checking order and delivery status with an AI agent
- Reading a PDF that opens inside the browser
- Summarising a long page or thread with an AI agent
- Collecting every image on a page with its caption
- Collecting event and course listings with an AI agent
- Cancelling a subscription with an AI agent
- What an AI agent can and cannot do inside an iframe
- Shadow DOM and an AI agent: you can click it, you cannot read it
- How to add a browser to Codex as an MCP server
- What a page snapshot costs, per control
- How to let Gemini CLI use a browser
- Native selects and the ones that only look like selects
- Clicking by selector or by coordinates
- How long the agent waits before it gives up
- What a second browser costs
- Uploading a file with an AI agent, and why this one cannot
- Watching the agent work, and when it is worth it
- When not to use an AI browser agent
- Agent or script: deciding once instead of every time
- Using the keyboard instead of the mouse
- Secrets in an agent task: where they end up
- What an agent run should log
- Deduplicating what an AI agent collects
- Normalising values across sites
- Validating an AI agent's output
- Reading a table with an AI agent
- Driving a site's own search and filters
- The task works headed and fails headless
- How to let the AdaL CLI use a browser