From 4c7371bd45b389f3f4c56a3ac0dadcc3fe7a80b2 Mon Sep 17 00:00:00 2001
From: jeffalder <49817386+jeffalder@users.noreply.github.com>
Date: Fri, 2 Aug 2024 09:29:04 -0700
Subject: [PATCH] Add caveat to README

In troubleshooting https://github.com/bazelbuild/bazel/issues/23170, I had to dig deep into this code to understand what was happening. Bazel's default error does not apply to this situation, and Bazel's own debugging is also unhelpful. In fact, per the issue, in 7.x, you get `java.lang.NullPointerException: Cannot invoke "java.lang.Throwable.getMessage()" because "cause" is null`.

I think this change would at least make it easier for folks to identify this issue in their own builds.
---
 README.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/README.md b/README.md
index fd213f5..98ce14a 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,20 @@ package_lint_config({
 })
 ```
 
+### Missing `@@apple_linters` error
+
+Bazel may report an error like this:
+```
+ERROR: Failed to load Starlark extension '@@apple_linters//:defs.bzl'.
+Cycle in the workspace file detected. This indicates that a repository is used prior to being defined.
+The following chain of repository dependencies lead to the missing definition.
+ - @@apple_linters
+This could either mean you have to add the '@@apple_linters' repository with a statement like `http_archive` in your WORKSPACE file (note that transitive dependencies are not added automatically), or move an existing definition earlier in your WORKSPACE file.
+```
+
+The `@apple_linters` repository is defined when `lint_setup` is called. You'll need to figure out where `load("@apple_linters//:defs.bzl, ...)` is getting called, and modify your build to ensure that `lint_setup` is called _before_ linting is loaded.
+
+
 ### API Documentation
 
 Can be found in [the api docs](api.md)