Document build issues related to uncommon tool behaviors
Change-Id: I47b04b9685cee6d2d639a3722c2d708f3bf8596d
diff --git a/src/source/known-issues.md b/src/source/known-issues.md
index 1643055..1fad560 100644
--- a/src/source/known-issues.md
+++ b/src/source/known-issues.md
@@ -123,3 +123,18 @@
**Fix**: Use a "clean" shell, in which no previous
actions could have swapped the default compiler.
+
+## Build errors caused by non-default tool settings. ##
+
+**Symptom**: The build fails with various symptoms, possibly
+complinaing about missing files or files that have the
+wrong format. One such symptom is `member [...] in archive is not an object`.
+
+**Cause**: The Android build system tends to use many host tools
+and to rely on their default behaviors. Some settings change
+those tools' behaviors and make them behave in ways that
+confuse the build system. Variables known to cause such
+issues are `CDPATH` and `GREP_OPTIONS`.
+
+**Fix**: Build Android in an environment that has as few
+customizations as possible.
