Command-line flags

Severity

Error Prone lets the user enable and disable specific checks as well as override their built-in severity levels (warning vs. error) by passing options to the Error Prone compiler invocation.

A valid Error Prone command-line option looks like:

-Xep:<checkName>[:severity]

checkName is required and is the canonical name of the check, e.g. “ReferenceEquality”. severity is one of {“OFF”, “WARN”, “ERROR”}. Multiple flags must be passed to enable or disable multiple checks. The last flag for a specific check wins.

Examples of usage follow:

-Xep:ReferenceEquality  [turns on ReferenceEquality check with the severity level from its BugPattern annotation]
-Xep:ReferenceEquality:OFF  [turns off ReferenceEquality check]
-Xep:ReferenceEquality:WARN  [turns on ReferenceEquality check as a warning]
-Xep:ReferenceEquality:ERROR  [turns on ReferenceEquality check as an error]
-Xep:ReferenceEquality:OFF -Xep:ReferenceEquality  [turns on ReferenceEquality check]

There are also a few blanket severity-changing flags:

  • -XepAllErrorsAsWarnings
  • -XepAllSuggestionsAsWarnings
  • -XepAllDisabledChecksAsWarnings
  • -XepDisableAllChecks
  • -XepDisableAllWarnings
  • -XepDisableWarningsInGeneratedCode : Disables warnings in classes annotated with @Generated

With any of the blanket flags, you can pass additional flags afterward to tweak the level of individual checks. E.g., this flag combination disables all checks except for ReferenceEquality:

-XepDisableAllChecks -Xep:ReferenceEquality:ERROR

Additionally, you can completely exclude certain paths from any Error Prone checking via the -XepExcludedPaths flag. The flag takes as an argument a regular expression that is matched against a source file’s path to determine whether it should be excluded. So, to exclude files in any sub-directory of a path containing build/generated, use the option:

-XepExcludedPaths:.*/build/generated/.*

If you pass a flag that refers to an unknown check name, by default Error Prone will throw an error. You can allow the use of unknown check names by passing the -XepIgnoreUnknownCheckNames flag.

We no longer support the old-style Error Prone disabling flags that used the -Xepdisable:<checkName> syntax.

Patching

There are a couple of flags for configuration of patching in suggested fixes, e.g. -XepPatchChecks:VALUE and -XepPatchLocation:VALUE. See the patching docs for more info.

Pass Additional Info to BugCheckers

To configure checks, you can use custom flags to pass info directly to BugCheckers. A valid custom flag looks like this:

-XepOpt:[Namespace:]FlagName[=Value]

By convention, if a flag is only relevant to one check or a group of checks, to prevent name collision, you should prefix your flag’s name with an optional namespace and a colon, e.g. -XepOpt:JUnit4TestNotRun:ExpandedHeuristic=true.

If a flag is set with no value provided, that flag is set to true, e.g. -XepOpt:MakeAwesome is equivalent to -XepOpt:MakeAwesome=true.

Some examples:

-XepOpt:FlagName=SomeValue        (flags["FlagName"] = "SomeValue")
-XepOpt:BooleanFlag               (flags["BooleanFlag"] = "true")
-XepOpt:ListFlag=1,2,3            (flags["ListFlag"] = "1,2,3")
-XepOpt:Namespace:SomeFlag=AValue (flags["Namespace:SomeFlag"] = "AValue")

These flags can be accessed in a BugChecker just by adding a one-argument constructor that takes an ErrorProneFlags object, like so:

public class MyChecker extends BugChecker implements SomeTreeMatcher {

  private final boolean coolness;

  public MyChecker(ErrorProneFlags flags) {
    // The ErrorProneFlags get* methods return an Optional<*>, use
    // Optional.orElse(...) and related methods to get with default, etc.
    this.coolness = flags.getBoolean("ErrorProne:IsCool").orElse(true);
  }

  public Description matchSomething(...) {...}
}

Configuration file

All arguments that are passed as -Xep* after -Xplugin:ErrorProne can also be passed through a configuration file using @.

This allows easier sharing of errorprone configurations between various build systems (cli, maven, gradle, bazel, etc) and works around platform dependent line wrapping rules.

The configuration file allows # as comment, both full line and inline.

Example:

-XepAllErrorsAsWarnings
-XepAllSuggestionsAsWarnings
-XepDisableWarningsInGeneratedCode
# This library back-ports `java.time`, so we need the old APIs
-Xep:JavaUtilDate:OFF
# Bug #123
-Xep:JUnit4TestNotRun:OFF
# Indends and trailing spaces are OK:
   -Xep:MisusedDayOfYear:WARN
   -Xep:MisusedWeekYear:WARN
# Several flags in one single line are OK:
-Xep:EffectivelyPrivate:OFF -Xep:ReturnValueIgnored:OFF   -Xep:EmptyBlockTag:OFF
# Empty lines are OK

-Xep:ReturnValueIgnored:WARN # Inline comments are OK

Using it in command line:

@~/project/errorprone.cfg

NOTE: the ~ in the example above will not work in Windows, or Gradle, or Maven, as it is expanded by the shell.
You will need to use the methods specific to your platform and build system.

NOTE: it is supported to pass a mixture of flags and several arguments files. The final value of a flag will be the one set that last time, regardless if that was done in directly or in am arguments file.

Maven

To pass Error Prone flags to Maven, use the compilerArgs parameter in the plugin’s configuration. The flags must be appended to the arg entry containing -Xplugin:ErrorProne. To enable warnings, the showWarnings parameter must also be set:

<project>
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <showWarnings>true</showWarnings>
          <compilerArgs>
            <arg>-XDcompilePolicy=simple</arg>
            <arg>--should-stop=ifError=FLOW</arg>
            <arg>-Xplugin:ErrorProne -Xep:DeadException:WARN -Xep:GuardedBy:OFF</arg>
          </compilerArgs>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Be aware that when running on JDK 8 the flags cannot be wrapped across multiple lines. JDK 9 and above do allow the flags to be separated by newlines. That is, the second <arg> element above can also be formatted as follows on JDK 9+, but not on JDK 8:

<arg>
  -Xplugin:ErrorProne \
  -Xep:DeadException:WARN \
  -Xep:GuardedBy:OFF
</arg>

NOTE: using multi-line <arg>s does not work on Windows when <fork> is enabled, see https://github.com/google/error-prone/issues/4256

NOTE: using an argument file (with @) allows bypassing this line wrapping bug:

<compilerArgs>
  ...
  <arg>-Xplugin:ErrorProne @${project.basedir}/errorprone.cfg</arg>
</compilerArgs>

And move the flags to errorprone.cfg:

-Xep:DeadException:WARN
-Xep:GuardedBy:OFF