ScreenshotNeo

BlogHow-to

Why Chrome Headless Uses the Wrong Profile and How to Fix It

Chrome Headless usually uses the wrong profile because its user-data parent, executable, or process differs. Learn deterministic fixes for CLI, Puppeteer, Selenium, and CI.

By the ScreenshotNeo team30 September 20268 min read

Why Chrome Headless Uses the Wrong Profile and How to Fix It

Direct answer: Chrome Headless does not have a special profile system. It uses whichever Chrome user-data directory and profile the launched browser selects. The most common error is passing a profile directory such as .../User Data/Profile 1 as --user-data-dir. The flag expects the parent directory, .../User Data, which contains Default, Profile 1, and Chrome’s per-installation state.

Headless also may be launching a different Chrome channel, executable, operating-system account, framework-created temporary directory, or concurrent process. Fix the path and executable first, then control concurrency. Modern Headless shares Chrome’s main code path with headful Chrome; it runs without visible UI but does not inherently discard profile data. Chrome’s Headless documentation describes this unified behavior.

How Chrome profile paths are organized

Chrome separates the user-data directory from an individual profile. Chromium’s User Data Directory documentation says the parent contains history, bookmarks, cookies, and other local state. Profiles are subdirectories within it, commonly named Default and Profile 1.

Path or setting What it means What to pass
/home/alice/.config/google-chrome User-data directory (parent) --user-data-dir=/home/alice/.config/google-chrome
/home/alice/.config/google-chrome/Profile 1 One profile inside that parent Usually do not pass as --user-data-dir
Default or Profile 1 Profile directory name Use --profile-directory=Profile 1 when needed

The path shown as Profile Path on chrome://version is the child profile directory. Its parent is the value normally required for --user-data-dir. If you pass the child as the parent, Chrome can create a new nested layout and appear to ignore your cookies or extensions.

Diagnose the mismatch deterministically

  1. Inspect the working browser. Open the profile that has the expected cookies and extensions, visit chrome://version, and copy Profile Path.
  2. Derive the parent. Remove the final /Default or /Profile 1 component. That parent is the candidate user-data directory.
  3. Identify the executable. Log the exact binary used by automation. Stable, Beta, Dev, Canary, Chromium, and Chrome for Testing can use different defaults and profile roots.
  4. Log the final arguments. Puppeteer, Selenium, containers, and test runners may add a temporary --user-data-dir. The argument visible in your source code may not be the final command line.
  5. Check ownership. A running Chrome process can lock a persistent directory. Close visible Chrome before testing, or use a separate automation directory.
  6. Confirm the operating-system account. A service account, container user, or CI runner has a different home directory and therefore different default paths.

Chromium’s documentation also notes that channel and platform defaults differ, and that on Linux --user-data-dir takes precedence over CHROME_USER_DATA_DIR. Treat every path as explicit in production automation.

The user-data directory is the parent; Default and Profile 1 are child profiles.
The user-data directory is the parent; Default and Profile 1 are child profiles.

Fix the command-line launch

Use the parent directory when you want an existing profile tree:

google-chrome \
  --headless \
  --user-data-dir="/absolute/path/to/Chrome/User Data"

If you specifically need Profile 1 inside that parent, add the profile selector:

google-chrome \
  --headless \
  --user-data-dir="/absolute/path/to/Chrome/User Data" \
  --profile-directory="Profile 1"

For repeatable tests, a clean directory is usually safer:

google-chrome \
  --headless \
  --user-data-dir="/tmp/chrome-automation-profile"

Chrome initializes an empty directory with the required profile files. The Chromium profile guide recommends a separate folder for development and testing. Use an absolute path, ensure the automation user can read and write it, and remove temporary directories after the browser exits.

Puppeteer: select a persistent or isolated profile

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  userDataDir: '/absolute/path/to/automation-profile',
  executablePath: '/usr/bin/google-chrome'
});

const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'networkidle2'});
console.log(await page.title());
await browser.close();

userDataDir should be the parent you intend to reuse, or a purpose-built empty directory. If you need a particular child profile, pass Chrome’s profile argument through args:

const browser = await puppeteer.launch({
  headless: true,
  userDataDir: '/absolute/path/to/Chrome/User Data',
  args: ['--profile-directory=Profile 1']
});

Do not point two concurrent Puppeteer browsers at one persistent directory. Generate one directory per job, wait for browser.close(), and delete it only after all child processes have stopped. A copied profile is safer than using your daily profile because automation can change cookies, cache, local storage, extensions, and settings.

Selenium: set ChromeOptions correctly

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public class HeadlessProfile {
  public static void main(String[] args) {
    ChromeOptions options = new ChromeOptions();
    options.addArguments("--headless=new");
    options.addArguments("--user-data-dir=/absolute/path/to/automation-profile");
    options.addArguments("--window-size=1440,900");

    WebDriver driver = new ChromeDriver(options);
    try {
      driver.get("https://example.com");
      System.out.println(driver.getTitle());
    } finally {
      driver.quit();
    }
  }
}

Selenium documents both --headless=new and --user-data-dir=... as common Chrome arguments. Chrome and ChromeDriver major versions must match; a stale driver can fail before profile selection is even reached. Verify the versions of the exact Chrome binary and driver installed on the machine.

Remote debugging and chrome-devtools-mcp

Close existing Chrome instances, start the intended binary with a dedicated directory, and then connect your client to the matching port:

/usr/bin/google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile-stable

The chrome-devtools-mcp documentation explains that its persistent profile is reused between runs, only one browser can use it at a time, and --isolated creates a temporary directory. Remote debugging should use a non-default directory so it does not collide with an already-running desktop browser. Keep the debugging port bound to a trusted interface and avoid exposing it publicly.

Profile selection in containers and CI

  • Set an explicit writable directory such as /work/chrome-profile or a per-job temporary path.
  • Run Chrome as the same user that owns the directory, or fix ownership before launch.
  • Do not assume /home/your-name/.config/google-chrome exists in a container.
  • Pin the Chrome channel and binary path. A system package and a Chrome for Testing download may have different defaults.
  • Use one profile directory per worker. A Kubernetes replica, CI matrix job, or test shard must not share a mounted persistent profile.
  • Persist only the state you need. Reusing an entire desktop profile can include sensitive cookies and extensions.

Common errors and fixes

Symptom Likely cause Fix
Cookies or extensions are missing Wrong parent, wrong channel, or temporary launcher directory Compare chrome://version with the logged executable and final --user-data-dir.
A new Default appears inside Profile 1 Child profile was supplied as the user-data parent Pass the parent and optionally add --profile-directory=Profile 1.
Profile in use or startup failure Another Chrome process owns the directory Close it, use a unique directory, or serialize access.
Headless works locally but not in CI Different OS user, channel, home directory, or permissions Print whoami, executable path, directory permissions, and all Chrome arguments.
Selenium cannot create a session ChromeDriver major version does not match Chrome Install a matching driver and verify both versions.
Changes disappear after each run Framework uses an ephemeral directory Set an explicit persistent userDataDir, or intentionally save and restore only required state.
Two tests interfere with one another Shared persistent directory Allocate a unique directory per test worker and clean it up after shutdown.
Parallel browser jobs need one profile directory per process.
Parallel browser jobs need one profile directory per process.

Persistence, concurrency, security, and reliability

Persistent versus clean state

A persistent profile preserves cookies, local storage, permissions, cache, and extensions. It is useful for workflows that require a logged-in session, but it makes tests order-dependent and can contain secrets. A clean temporary profile improves repeatability and avoids stale state. Choose deliberately rather than relying on a launcher default.

Concurrency

Chrome profile data is stateful. One directory per process is the reliable rule. For parallel work, create directories with a job identifier or operating-system temporary-directory API. Do not “solve” locking errors by deleting files from a profile that another Chrome process may still be using.

Performance

A warm persistent profile can avoid first-run initialization and may retain cache, but large caches and extensions can slow startup. Clean profiles cost startup time while making results more consistent. Disable unnecessary extensions, use a fixed viewport, and wait for a specific selector or network condition instead of arbitrary long sleeps.

Security

Profile directories contain cookies and other local state. Restrict filesystem permissions, avoid committing them to source control, and never upload them to logs or artifacts. Remote debugging exposes powerful browser control; bind it privately and close the process when finished.

Or skip the browser setup

If your goal is a clean website screenshot rather than browser-profile debugging, ScreenshotNeo provides a single GET request. Its capture service accepts consent banners before the shot and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.

See the ScreenshotNeo API documentation for all options, including full-page and element capture, device presets, dark mode, retina scale, custom CSS and JavaScript, clicks, waits, blocked resources, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous jobs, webhooks, bulk capture, usage, and PDF output.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. There are 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

Operational checklist

  • Copy Profile Path from chrome://version.
  • Pass its parent as --user-data-dir.
  • Use --profile-directory only to select a child such as Profile 1.
  • Pin the executable and Chrome channel.
  • Log final launch arguments in CI.
  • Use one profile directory per concurrent process.
  • Prefer a copied or clean profile over a daily profile.
  • Match ChromeDriver’s major version to Chrome.
  • Keep remote debugging private.

FAQ

Does --headless always use the Default profile?

No. It uses the profile selected by the user-data directory, profile argument, executable defaults, and existing state. If no explicit directory is supplied, the launcher or operating system determines the location.

Can I pass Profile 1 directly?

Use its parent with --user-data-dir and select Profile 1 with --profile-directory. Passing the child as the parent can create an unexpected nested profile.

Why does a profile work headful but not headless?

Usually the two launches differ in executable, user, arguments, or directory ownership. Compare the complete command lines and run each mode with an explicit directory.

Should automation reuse my personal Chrome profile?

Only when the workflow requires its state and you understand the security and concurrency risks. A dedicated copied or clean profile is easier to reproduce and protect.