diff --git a/docs/shared/guides/unknown-local-cache.md b/docs/shared/guides/unknown-local-cache.md index c106ddc8b0..50b726b2f0 100644 --- a/docs/shared/guides/unknown-local-cache.md +++ b/docs/shared/guides/unknown-local-cache.md @@ -1,6 +1,6 @@ # Unknown Local Cache Error -This document will explain why the following error happens and how to address it. +This document will explain why the following errors happen and how to address them. ``` NX Invalid Cache Directory for Task "myapp:build" @@ -11,6 +11,14 @@ If your machine ID has changed since the artifact was cached, run "nx reset" to Read about the error and how to address it here: https://nx.dev/troubleshooting/unknown-local-cache ``` +``` +NX Unrecognized Cache Artifacts + +Nx found unrecognized artifacts in the cache directory and will not be able to use them. +Nx can only restore artifacts it has metadata about. +Read about this warning and how to address it here: https://nx.dev/troubleshooting/unknown-local-cache +``` + ## Nx Tracks Cache Source Nx can cache tasks, which can drastically speed up your CI and local builds. However, this comes with the potential risk @@ -19,24 +27,24 @@ executes a task that matches the hash of the tainted artifact, they could retrie the outcome of the task. Nx and Nx Cloud contain several safeguards to minimize the likelihood of cache poisoning or, in the case of Nx Cloud, completely prevent it. -The error above is one such safeguard. +The errors above are some of these safeguards. Nx trusts the local cache. If you executed a task and stored the corresponding cached artifact on your machine, you can safely restore it on the same machine without worrying about cache poisoning. After all, in order to tamper with the cache artifact, the actor would need access to the machine itself. However, when artifacts in the local cache are created by a different machine, we cannot make such assumption. By -default, Nx will refuse to use such artifacts and will throw the "Invalid Cache Directory" error. +default, Nx will refuse to use such artifacts and will throw the "Invalid Cache Directory" error or "Unrecognized Cache Artifacts" error. ## Your MachineId Has Changed -Upgrading your computer's hardware may alter its Machine ID, yielding the error above. To fix it execute `nx reset` to +Upgrading your computer's hardware may alter its Machine ID, yielding one of the errors above. To fix it execute `nx reset` to remove all the cache directories created under the previous Machine ID. After doing so, you should no longer see the error. ## You Share Cache with Another Machine Using a Network Drive -You can prefix any Nx command with `NX_REJECT_UNKNOWN_LOCAL_CACHE=0` to ignore the error ( +You can prefix any Nx command with `NX_REJECT_UNKNOWN_LOCAL_CACHE=0` to ignore the errors ( e.g., `NX_REJECT_UNKNOWN_LOCAL_CACHE=0 nx run-many -t build test`). This is similar to setting `NODE_TLS_REJECT_UNAUTHORIZED=0` to ignore any errors stemming form self-signed certificates. Even though it will make it work, this approach is discouraged. @@ -65,9 +73,7 @@ allow overwrites. an access token gets compromised it can be easily removed, in turn deleting all the cache artifacts that were created using it. -Nx Replay is not the only remote cache you can use. If you are using a different remote cache or using your -own implementation, we would highly recommend ensuring that the same safety mechanisms as Nx Cloud have been put in -place. +Nx Replay is not the only remote cache you can use. You can also use one of the [Powerpack self-hosted remote cache plugins](/features/powerpack/custom-caching). These plugins offer the performance benefits of a remote cache, but do not have the same security guarantees as Nx Replay. ## Self-Hosted Remote Cache diff --git a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md index eabcb3136e..be47b3ff14 100644 --- a/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md +++ b/docs/shared/packages/powerpack-s3-cache/powerpack-s3-cache-plugin.md @@ -7,6 +7,10 @@ The `@nx/powerpack-s3-cache` plugin enables you to use an [Amazon S3](https://aw This plugin will enable the remote cache for your Nx workspace, but does not provide any of the other features of Nx Cloud. If you want to leverage [distributed task execution](/ci/features/distribute-task-execution), [re-running flaky tasks](/ci/features/flaky-tasks) or [automatically splitting tasks](/ci/features/split-e2e-tasks), you'll need to [connect to Nx Cloud](/ci/intro/connect-to-nx-cloud) and use [Nx Replay](/ci/features/remote-cache) instead. +{% callout type="warning" title="Potential Cache Poisoning" %} +Using your own Amazon S3 bucket to host the remote cache opens you up to the possibility of [cache poisoning](/troubleshooting/unknown-local-cache). To avoid this, use [Nx Replay](/ci/features/remote-cache). +{% /callout %} + {% callout title="This plugin requires an active Nx Powerpack license" %} In order to use `@nx/powerpack-s3-cache`, you need to have an active Powerpack license. If you don't have a license or it has expired, your cache will no longer be shared and each machine will use its local cache. {% /callout %} diff --git a/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md b/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md index b975a42f87..88489aeff6 100644 --- a/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md +++ b/docs/shared/packages/powerpack-shared-fs-cache/powerpack-shared-fs-cache-plugin.md @@ -8,7 +8,7 @@ The `@nx/powerpack-shared-fs-cache` plugin enables you to use a shared file syst This plugin will enable the remote cache for your Nx workspace, but does not provide any of the other features of Nx Cloud. If you want to leverage [distributed task execution](/ci/features/distribute-task-execution), [re-running flaky tasks](/ci/features/flaky-tasks) or [automatically splitting tasks](/ci/features/split-e2e-tasks), you'll need to [connect to Nx Cloud](/ci/intro/connect-to-nx-cloud) and use [Nx Replay](/ci/features/remote-cache) instead. {% callout type="warning" title="Potential Cache Poisoning" %} -Using a shared file system folder for the remote cache opens you up to the possibility of [cache poisoning](/troubleshooting/unknown-local-cache). To avoid this, use [Nx Replay](/ci/features/remote-cache) or share your cache with an AWS S3 bucket using [`@nx/powerpack-s3-cache`](/nx-api/powerpack-s3-cache). +Using a shared file system folder for the remote cache opens you up to the possibility of [cache poisoning](/troubleshooting/unknown-local-cache). To avoid this, use [Nx Replay](/ci/features/remote-cache). {% /callout %} {% callout title="This plugin requires an active Nx Powerpack license" %}