From ea20554eb77700dd8d5f8316a663961ea7c11bb0 Mon Sep 17 00:00:00 2001
From: Mike McCready <66998419+MikeMcC399@users.noreply.github.com>
Date: Thu, 9 Jan 2025 16:52:13 +0100
Subject: [PATCH] docs: add mitigation instructions non-root user not node
 (#1278)

---
 README.md                               | 20 ++++++++++++++++++++
 examples/included-as-non-root/README.md |  4 ++++
 2 files changed, 24 insertions(+)

diff --git a/README.md b/README.md
index cbf2f965d0..d97ad70067 100644
--- a/README.md
+++ b/README.md
@@ -185,6 +185,26 @@ ENV CYPRESS_SKIP_VERIFY=true
 
 or pass the environment variable as an additional CLI option `--env CYPRESS_SKIP_VERIFY=true` to the [docker run](https://docs.docker.com/reference/cli/docker/container/run/) command.
 
+## Fontconfig error: No writable cache directories
+
+### Problem
+
+If a Cypress Docker image is run with a non-root user other than `node` (`1000`) then Cypress may be unable to write into the Linux `$HOME` directory and may fail. The error message contains the text:
+
+```text
+Fontconfig error: No writable cache directories
+The Test Runner unexpectedly exited via a exit event with signal SIGTRAP
+```
+
+### Workaround
+
+Build a custom Docker image and add the following instructions to the end of the `Dockerfile` to allow the `$HOME` directory for the non-root user `node` to be used and to allow Cypress write access to the necessary cache directories:
+
+```Dockerfile
+ENV HOME=/home/node
+RUN chmod -R 777 $HOME /root/.cache/Cypress
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)
diff --git a/examples/included-as-non-root/README.md b/examples/included-as-non-root/README.md
index 54ac703709..901b81da52 100644
--- a/examples/included-as-non-root/README.md
+++ b/examples/included-as-non-root/README.md
@@ -34,6 +34,10 @@ docker run --rm -v .:/test -w /test -u node cypress/included
 
 You can expect this command to run successfully.
 
+### Non-root user not node 1000
+
+If you need to run a `cypress/included` image with a non-root user other than `node` (`1000`) and you are experiencing permissions errors, please refer to the [Known Problems](../../README.md#known-problems) section regarding workarounds.
+
 ## GitHub Actions
 
 In general when running Cypress Docker images in GitHub Actions it is recommended to use the GitHub Actions' `container` syntax (see [Running jobs in a container](https://docs.github.com/en/actions/writing-workflows/choosing-where-your-workflow-runs/running-jobs-in-a-container) and [.github/workflows/example-cypress-github-action.yml](../../.github/workflows/example-cypress-github-action.yml)).