(spark) branch branch-4.x updated: [SPARK-58827][DOC] Document SPARK_LOCAL_IP for local RemoteClassLoaderError test failures

[sz...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

szehon-ho pushed a commit to branch branch-4.x
in repository https://gitbox.apache.org/repos/asf/spark.git


The following commit(s) were added to refs/heads/branch-4.x by this push:
     new b6d85fd97428 [SPARK-58827][DOC] Document SPARK_LOCAL_IP for local RemoteClassLoaderError test failures
b6d85fd97428 is described below

commit b6d85fd9742805f3b5bc8ced8b4ddabe44c94c59
Author: Szehon Ho <sz...@gmail.com>
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 <sz...@gmail.com>
    Signed-off-by: Szehon Ho <sz...@gmail.com>
    (cherry picked from commit f0c247a4d61436e4daf9cc139d045d14119dca40)
    Signed-off-by: Szehon Ho <sz...@gmail.com>
---
 AGENTS.md              | 3 +++
 docs/building-spark.md | 9 +++++++++
 2 files changed, 12 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1d2fc98b6c7e..5f56cacfb713 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -103,6 +103,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: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org