What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A “symbol not found” or “Error relocating” message in a Headless Chrome Docker image usually means the dynamic loader cannot find a required symbol in the shared library it selected. The fix depends on the exact symbol, browser binary, base image, architecture and library versions—not just on the wording of the error. Start by inspecting the browser and its dependencies inside the failing container, then align the browser, automation framework and system libraries.
What the error means—and what it does not
When a process starts, the dynamic loader connects the executable to the shared libraries it needs. A missing library and a missing symbol are related but distinct problems: a library may be absent, or it may be present but not provide the symbol or ABI version the browser expects. In the latter case, installing another package with a similar name may not help; the loader may be selecting an incompatible copy.
As an Amazon Associate I earn from qualifying purchases.
For example, a historical Puppeteer issue reported Error relocating /usr/lib/chromium/chrome: FT_Get_Color_Glyph_Layer: symbol not found and FT_Palette_Select: symbol not found. That report was opened on 2019-04-23 and is an example of the error, not proof of a universal cause or current fix. The issue report does not establish a repair for an unspecified image.
Do not assume that changing a font package or disabling Chrome’s sandbox resolves a relocation error. The full error and the dependency resolution in the actual container should determine what to change.
#1 Best Overall
Diagnose the failing container first
1. Record the runtime context
Before changing the Dockerfile, capture enough detail to make the failure reproducible:
- The complete error, including the missing symbol and executable path.
- The image tag or digest, base distribution and version, and CPU architecture.
- The browser executable actually launched and its version.
- The automation package and version (for example, Puppeteer or Playwright).
- Whether the image uses glibc or musl.
A generic “Chrome failed to launch” message may conceal a different failure. Keep the exact image and command in your notes while investigating.
2. Inspect the executable and unresolved dependencies
Run the check inside the same image and environment that fails, using the executable path from the error or your launch configuration:
Rank #2
ldd /path/to/chrome | grep notPuppeteer’s troubleshooting guide recommends this approach to identify missing dependencies. Puppeteer troubleshooting If your binary is named chromium, substitute its actual path. No output from grep not does not, by itself, rule out an incompatible symbol version: if the library is present but the symbol remains unresolved, find which library copy the loader selects and check its version and ABI compatibility.
3. Check the base distribution against your framework
Do not treat Puppeteer and Playwright support statements as interchangeable:
- Playwright: its official Docker guidance says Alpine Linux and other musl-based distributions are not supported. If you use Playwright, use a supported image rather than trying to make an unsupported Alpine setup work. Playwright Docker guidance
- Puppeteer: its troubleshooting guide says Chrome does not support Alpine out of the box; users must supply compatible system dependencies and test the image. This is conditional guidance, not a guarantee that a particular Alpine image or Chromium package will work. Puppeteer troubleshooting
Also confirm that the image provides the required libraries for its CPU architecture. A package name or install command that works in one distribution or architecture may not provide the same library build in another.
Rank #3
Choose a compatible browser and image
Match the browser to the automation package
For Puppeteer, check the official supported-browser mapping and use the browser version associated with the Puppeteer release in your application. Puppeteer supported browsers For Playwright, keep the Docker image’s Playwright version aligned with the package version in the application; the official Docker guide warns that a mismatch can prevent the browser executable from being found. Avoid copying old version pins from an unrelated report and treating them as a current fix.
Recommended Free Tools
Consider an official framework image
Puppeteer’s official Docker image provides Chrome for Testing, dependencies and a pre-installed Puppeteer version. Its documented sandboxed run requires SYS_ADMIN, and the guide recommends using an init process to manage child processes. Check that your deployment platform permits those runtime requirements before adopting the image. Puppeteer Docker guide
Compare candidate images on the things that affect whether they will run reliably:
- Framework support for the distribution and libc family.
- Browser-to-automation version compatibility.
- Availability of the required libraries for the target architecture.
- Whether you can pin and rebuild the image reproducibly.
- Sandbox permissions and child-process management requirements.
A small Alpine image is not automatically the best choice if the browser build expects glibc or a different library version.
Apply the change and verify it in the final image
- Make one targeted change. Use a supported distribution, compatible browser build or correctly matched library version based on the diagnostic output. Avoid changing several packages at once; it makes the cause harder to identify.
- Pin the relevant versions. Keep the image and browser/framework package versions consistent with the official guidance so that a later rebuild does not silently change the runtime combination.
- Rebuild the image you will deploy. Do not rely on a local host’s libraries or on a different development container.
- Run the exact browser launch command inside that image. Confirm that it launches and that the original missing-symbol error is gone.
- Retain the diagnostic details. Keep the image identifier, architecture, browser and framework versions, full error and dependency output with the build or incident notes.
Common failure paths
lddreports a missing library: identify the named dependency and install the compatible package for the image’s distribution and architecture. Re-run the check in the rebuilt container.- Libraries appear present, but the symbol is still missing: investigate ABI or version mismatch and determine which copy of the library the loader actually selects. Adding a similarly named package is not a diagnosis.
- The image is Alpine with Playwright: Playwright’s Docker guidance does not support Alpine or other musl-based distributions; switch to a supported base image rather than treating the issue as a missing-package puzzle.
- The image is Alpine with Puppeteer: Puppeteer says Chrome does not work on Alpine out of the box. Supply compatible dependencies and test the image, or use an appropriate official Puppeteer image as a baseline.
- The browser executable cannot be found after changing versions: with Playwright, check that the Docker image version matches the application package. With Puppeteer, consult its supported-browser mapping rather than selecting an arbitrary browser pin.
- The error changed after a rebuild: compare the image, architecture, browser and library versions with the captured runtime context. A changed error can indicate that the rebuilt image resolves a different library combination.
Or skip the browser setup
If your goal is to capture a webpage rather than maintain Chrome in your own container, ScreenshotNeo offers a screenshot API and MCP server. One GET request returns an image or PDF; see the API documentation.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups and chat widgets before the shot. Bot checks, blank pages, failed loads and cache hits are not billed. Its MCP server lets AI agents use screenshot tools, and the Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up free for 1,000 screenshots a month, no card required.
FAQ
Does “symbol not found” always mean a package is missing?
No. The library may exist but lack the expected symbol or compatible ABI version. Inspect which library the loader selects.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Will disabling Chrome’s sandbox fix a relocation error?
There is no basis to treat disabling the sandbox as a fix for an unresolved shared-library symbol. Diagnose the binary and libraries first.
Can I use an old issue’s package versions as the fix?
Not safely without matching its image, architecture, browser and framework context. Use the current framework documentation and verify the resulting image.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
