This is an automated email from the ASF dual-hosted git repository.
szehon-ho pushed a commit to branch branch-4.3
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/branch-4.3 by this push:
new 756c6e3b14f1 [SPARK-58827][DOC] Document SPARK_LOCAL_IP for local
RemoteClassLoaderError test failures
756c6e3b14f1 is described below
commit 756c6e3b14f16ee6ec5fcaa7668380c1bf81d1f1
Author: Szehon Ho <[email protected]>
AuthorDate: Tue Aug 18 16:47:36 2026 -0700
[SPARK-58827][DOC] Document SPARK_LOCAL_IP for local RemoteClassLoaderError
test failures
### What changes were proposed in this pull request?
- Add a short **Local network binding** note near the end of Running Tests
in `docs/building-spark.md`, recommending `export SPARK_LOCAL_IP=localhost`
when local tests fail due to binding to a non-loopback interface (e.g. VPN).
- Add a generic pointer in `AGENTS.md` to `docs/building-spark.md` for
build/test setup and troubleshooting.
### Why are the changes needed?
`SPARK_LOCAL_IP` is already listed in the Configuration Guide as a
deploy-time env var, but contributor / test docs do not mention this failure
mode. Local tests can fail with `RemoteClassLoaderError` or Netty `Connection
reset by peer` even though the code under test is fine.
### Does this PR introduce _any_ user-facing change?
No. Documentation / agent-instructions only.
### How was this patch tested?
N/A (docs). The same `SPARK_LOCAL_IP=localhost` workaround was verified
locally when running AutoCDC suites.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Cursor Grok 4.5
Closes #58053 from szehon-ho/docs-spark-local-ip-tests.
Authored-by: Szehon Ho <[email protected]>
Signed-off-by: Szehon Ho <[email protected]>
(cherry picked from commit f0c247a4d61436e4daf9cc139d045d14119dca40)
Signed-off-by: Szehon Ho <[email protected]>
---
AGENTS.md | 3 +++
docs/building-spark.md | 9 +++++++++
2 files changed, 12 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
index 11bc4ad9484d..7aa8801b060b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,9 @@ These are combined with a base above rather than used on
their own:
Build and tests can take a long time. If the user explicitly asked to run
tests, run them. Otherwise (you are running tests on your own to verify a
change), first ask the user if they have more changes to make.
+For build and test setup, including how to run tests and troubleshoot common
+local failures, see `docs/building-spark.md`.
+
Prefer SBT over Maven for faster incremental compilation. Module names are
defined in `project/SparkBuild.scala`.
Compile a single module:
diff --git a/docs/building-spark.md b/docs/building-spark.md
index 0cae594af2e3..1b8dfa8d1b2b 100644
--- a/docs/building-spark.md
+++ b/docs/building-spark.md
@@ -270,6 +270,15 @@ or
./build/sbt -Pdocker-integration-tests docker-integration-tests/test
+## Local network binding
+
+On a machine with multiple network interfaces (for example a VPN), Spark may
bind to a
+non-loopback address, causing local tests to fail with errors such as
+`RemoteClassLoaderError` or Netty `Connection reset by peer`. Forcing the
loopback
+interface usually resolves this:
+
+ export SPARK_LOCAL_IP=localhost
+
<!---
## Change Scala Version
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
