CamoFox Docker Starts but Cannot Open a Tab? Check the Install

If your CamoFox Docker image builds and the server answers, but creating a tab fails with “installed Camoufox version could not be determined,” check the browser installation inside the container before deleting a profile. A running API is not proof that the browser binary is available. Preserve your profiles, inspect the exact image and runtime user, then prove that one disposable tab can open before reconnecting the agent workflow.

This guide is for someone who already runs CamoFox Browser Server in Docker and is stuck before the first usable tab. CamoFox provides the browser-side REST service; CamoFox MCP is the companion that exposes browser tools to an MCP client. Changing the client’s prompt will not install a missing browser in the server container.

Evidence scope: the installation failure below was reported for CamoFox Browser 2.4.8 on 14 October 2026. The explanation also uses pinned project source. We did not reproduce that Docker failure or independently test the reporter’s memory workaround. The hero is a concept illustration, not a product screenshot or a repair result.

Recognize the installation error, not just “HTTP 500”

In GitHub issue #38, a user reported a Docker build that completed despite a failed Camoufox fetch. The later POST /tabs request failed with a profile-compatibility message containing this decisive phrase:

installed Camoufox version could not be determined

The same message suggested resolving the installation or deleting a profile directory. The reporter said deleting the profile did not help: the browser cache was still incomplete. That is why the exact error matters. A browser-version lookup failure and a profile created with a different, known browser version are different starting conditions.

The pinned context-pool implementation checks the installed browser version before comparing it with the profile’s recorded version. If the installed version is unknown, it throws before that comparison. If two known versions differ, it throws a separate mismatch error.

• Installed version cannot be determined: investigate the browser installation and version-reader path first.
• Profile was created with version A, current version is B: investigate compatibility after preserving that profile. Do not treat this guide as permission to erase it.
• Connection refused or unreachable service: investigate the service address, container network and listening port first.
• Unauthorized, forbidden or missing request fields: correct authentication or request shape before diagnosing an installation failure.

Separate API reachability from browser readiness

The checked health-route source returns service and context-pool information. It does not create a new browser context. Its browserConnected value is derived from active user IDs. A reachable health endpoint with no active contexts does not, by itself, establish either a missing installation or a working first tab.

There is an important documentation distinction: the checked README’s API table describes /health as also pre-launching the browser, but the pinned route above does not perform that launch. For this troubleshooting decision, use the route’s actual behavior and a separate disposable-tab check—not a stronger interpretation of the label.

Keep the evidence in three layers:

1. Service: can the intended client reach the intended CamoFox server?
2. Installation: can the runtime user read the installed Camoufox version and browser files?
3. Browser task: can a dedicated test tab open, navigate to an authorized harmless page, and return useful page evidence?

Inside another container, localhost means that container. Use the Browser service’s approved address on your Docker network. Do not disable authentication or expose a private server publicly just to make a connectivity test pass. Once tabs work, our n8n session-reuse guide covers passing the same task identity between HTTP nodes.

Inspect the container without resetting its profile

Start with read-only inspection. Replace the example container name below with your existing container’s name. These commands are an illustrative diagnostic checklist, not output from our test. They do not fetch a browser or delete data.

CONTAINER='your-camofox-container'
docker inspect "$CONTAINER" --format 'image={{.Image}} user={{.Config.User}}'
docker inspect "$CONTAINER" --format '{{range .Mounts}}{{println .Destination}}{{end}}'
docker exec "$CONTAINER" sh -lc 'id; printf "HOME=%s\n" "$HOME"'

Record the image ID rather than only a tag that may have moved. Check where persistent state is mounted. The project’s Dockerfile sets the profile directory under /home/node/.camofox/profiles and declares /home/node/.camofox as persistent storage. The browser cache reported in this incident was under /home/node/.cache/camoufox. They are different locations: preserving profiles does not prove that the image contains the browser.

For the project’s default node-user image, inspect the two files named in the report:

docker exec "$CONTAINER" sh -lc '
  ls -l /home/node/.cache/camoufox/version.json \
        /home/node/.cache/camoufox/properties.json
'

Interpretation: “No such file” is evidence that these expected paths are missing in that container. It is not proof of the cause. If you use a custom runtime user, home directory or cache layout, establish that layout before treating the default paths as authoritative. Permission failures point to a different check than missing files. Finding both files is only a partial check, not proof that every browser file is complete.

Next, ask the installed package’s version reader, in the same runtime context:

docker exec "$CONTAINER" node -e '
  const pkgman = require("camoufox-js/dist/pkgman.js");
  console.log(pkgman.installedVerStr());
'

This diagnostic uses the same deep-imported function as the checked CamoFox source. It is an implementation-specific probe, not a stable public API. Preserve the returned value or exact error. The CamoFox wrapper catches a version-reader exception and reports unknown; missing files are one possible explanation, but an import or version-reader problem must not be silently relabeled as a missing binary.

Do not remove the profile, its volume, or the cache to “start clean” before saving this evidence. Profiles can contain valuable session state. If maintenance later needs a reset, stop dependent work, back up the relevant state and obtain the appropriate approval first.

Check the build log and the Docker VM’s memory

The pinned Dockerfile runs npx --yes camoufox-js fetch || true; the pinned package.json similarly tolerates fetch failure in postinstall. The shell fallback means that the surrounding step can succeed after a failed fetch. It does not mean that every build lacks a browser.

The reporter’s follow-up comment noted that a project test deliberately preserves this tolerant-build behavior. The requested upstream decision was whether to fail the build or make a missing browser clearer at runtime. Do not describe removing the fallback as an accepted upstream fix.

Read the browser-fetch portion of your saved build log. Look for a failed download, extraction failure, Killed, or an error that was followed by a successful overall build. Keep unrelated secrets and environment values out of any shared log.

In related issue #39, the same reporter described a memory-constrained Colima VM: the fetch was killed with exit 137 in a 2 GB VM, and increasing the VM to 8 GB was reported to get past it. That is one environment’s reported mitigation, not a universal minimum or a guaranteed fix. The two issues are one reporter’s linked incident, not two independent demonstrations.

docker info --format '{{.MemTotal}} {{.NCPU}}'
docker inspect "$CONTAINER" --format 'memoryLimit={{.HostConfig.Memory}}'

The first command reports the Docker daemon’s environment. On a desktop VM setup, that can differ from your physical computer’s RAM. The second reports a configured container memory limit; it is not a peak-usage measurement. A stopped runtime container’s status also cannot establish why an earlier build-stage process was killed.

Exit 137 means a SIGKILL-style termination; it is not sufficient by itself to prove out-of-memory. Correlate it with available VM/build diagnostics, configured limits and the actual fetch log. Docker’s resource-constraint documentation explains container memory limits and OOM behavior.

Choose a repair that matches the evidence

• Fetch failed and expected files are missing: arrange a controlled rebuild or installation repair using the project’s supported fetch path. Resolve the observed network, disk or memory constraint first; retain the original image and profile backup until validation succeeds.
• Default paths are missing but you customized the runtime: locate the actual browser cache and verify access as the service user before downloading another copy.
• Files exist but the version reader fails: investigate package resolution, permissions and the installed CamoFox/Camoufox combination. Preserve exact versions and errors; do not blindly switch browser releases.
• Known installed version conflicts with a saved profile: use a separate disposable identity to distinguish launch capability from that profile’s compatibility problem. Decide any migration or reset separately.
• A tab opens but a website fails: installation is no longer the only question. Move to page-state and navigation diagnosis rather than repeatedly rebuilding the image.

Rebuilding or restarting a Docker VM can interrupt other workloads. Treat it as planned maintenance, not the first diagnostic step. A browser fetched only into a running container’s writable layer may be lost when that container is replaced unless your deployment deliberately preserves that cache. Validate the replacement artifact you intend to keep, not just a temporarily repaired instance.

Prove one disposable tab before resuming the agent

After the installation repair, use a dedicated, non-sensitive test identity. The core POST /tabs route requires userId and sessionKey (or the supported listItemId alias). This illustrative body opens a blank tab without a login or business action:

{
  "userId": "install-check-dedicated",
  "sessionKey": "install-check-first-tab"
}

Use a unique identity reserved for your check, your existing approved server address and its required authentication. The source’s successful response contains tabId and url. A returned tab ID demonstrates that this request progressed past provisioning; it does not establish that your eventual target site works.

1. Retain the new tab ID. List tabs under the same userId and confirm that exact ID is present.
2. Navigate that tab to a harmless page you are authorized to inspect. Verify the resolved URL and expected page content with a snapshot or screenshot.
3. Close only that test tab using DELETE /tabs/:tabId with the same userId. List that user’s tabs again and confirm the ID is absent.
4. Only then reconnect the original agent workflow. Verify its first intended read-only step before allowing consequential actions.

If provisioning still fails, stop at that layer. There is no page trace to collect for a tab that never existed. If navigation succeeds but the task remains incomplete, use our CamoFox traces and console guide for the next diagnostic stage.

Keep a useful incident pack—and take the right next step

A useful support report contains the image ID, CamoFox package version, relevant Camoufox version or version-reader error, host architecture, Docker VM and container limits, exact tab-creation error, runtime user, checked cache paths and a sanitized fetch-log excerpt. Include whether a disposable identity could open a tab. Omit cookies, tokens, profile contents and unrelated customer data.

The practical goal is not merely to make Docker report a healthy container. It is to establish a usable browser while preserving existing session state. Explore CamoFox Browser Server and its official repository for the deployment contract. Add CamoFox MCP when you need an MCP client to drive that verified browser—not as a substitute for verifying the server installation.

FAQ

Should I delete the profile when the error suggests it?

Not as the first response to “installed Camoufox version could not be determined.” The checked source fails before comparing profile versions, and the incident reporter found that deleting a profile did not repair the missing installation. Preserve state and identify the failing layer first.

Does a healthy Docker container prove CamoFox can browse?

No. The checked health route reports service and pool state without launching a new context. Prove a disposable tab and then a harmless navigation separately.

Does CamoFox always need 8 GB?

This evidence does not establish that. The 8 GB figure is a reported workaround for one Colima build environment. Build-time extraction and runtime browsing are different workloads, and your platform, package versions and configured limits matter.

Are issues #38 and #39 fixed?

Both were open when checked on 14 October 2026. The saved evidence contains one follow-up comment on #38 and no comments on #39. Check their current status before applying future advice; an issue’s status alone would not prove that your existing image was rebuilt correctly.