EnvironmentalExecException: exit as LOCAL_ENVIRONMENTAL_ERROR
Based on an audit of all callers, I conclude that this exception is
primarily used to indicate a local system failure / misconfiguration,
e.g., inability to create an output directory due to missing
permissions.
PiperOrigin-RevId: 278370943
diff --git a/src/main/java/com/google/devtools/build/lib/actions/EnvironmentalExecException.java b/src/main/java/com/google/devtools/build/lib/actions/EnvironmentalExecException.java
index 08c68e5..37df0c9 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/EnvironmentalExecException.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/EnvironmentalExecException.java
@@ -15,19 +15,21 @@
package com.google.devtools.build.lib.actions;
import com.google.common.base.Throwables;
+import com.google.devtools.build.lib.util.ExitCode;
import java.io.IOException;
/**
- * An ExecException which is results from an external problem on the user's
+ * An ExecException which is reports an issue executing an action due to an external problem on the
* local system.
*
- * <p>Note that this is fundamentally different exception then the higher level
- * LocalEnvironmentException, which is thrown from the BuildTool. That exception
- * is thrown when the higher levels of Blaze decide to exit.
+ * <p>This exception will result in an exit code regarded as a system error; avoid using this for
+ * problems which should be attributed to the user, e.g., a misconfigured BUILD file (use {@link
+ * UserExecException}) or an action returning a non-zero exit code (use {@link *
+ * com.google.devtools.build.lib.exec.SpawnExecException}.
*
- * <p>This exception is thrown when a low level error is encountered in the
- * strategy or client protocol layers. This does not necessarily mean we will
- * exit; we may just retry the action.
+ * <p>The most common use of this exception is to wrap an "unexpected" {@link IOException} thrown by
+ * an lower-level file system access or local process execution, e.g., failure to create a temporary
+ * directory or denied file system access.
*/
public class EnvironmentalExecException extends ExecException {
public EnvironmentalExecException(IOException cause) {
@@ -52,10 +54,12 @@
+ getMessage()
+ "\n"
+ Throwables.getStackTraceAsString(getCause());
- return new ActionExecutionException(message, action, isCatastrophic());
+ return new ActionExecutionException(
+ message, action, isCatastrophic(), ExitCode.LOCAL_ENVIRONMENTAL_ERROR);
} else {
String message = messagePrefix + " failed due to " + getMessage();
- return new ActionExecutionException(message, action, isCatastrophic());
+ return new ActionExecutionException(
+ message, action, isCatastrophic(), ExitCode.LOCAL_ENVIRONMENTAL_ERROR);
}
}
}
