• Gauge logs are created under the logs directory in the project.
  • Two log files are created
    • gauge.log - logs for test execution
    • api.log - logs for gauge core api exposed for plugins
  • To customize logs directory set the logs_directory property in the env/default/ file to a custom logs directory path.
logs_directory = my_logs_dir
  • For non-project specific actions like plugin installation log files are created in the following location.
Windows - %APPDATA%\gauge\logs
MacOS*  - <user_home>/.gauge/logs
Linux   - <user_home>/.gauge/logs

Gauge Installation


  • The default installation location is %ProgramFiles%\gauge.
  • gauge_install_location\bin should be in PATH to run from command line.
  • Gauge plugins are installed at %APPDATA%\gauge\plugins directory.
  • APPDATA directory is usually located at C:\Users\USER_NAME\AppData\Roaming.

Mac OS X

  • The default installation location is /usr/local/.
  • usr/local/bin/ or custom_install_location/bin should be in PATH.
  • Run brew update before installing the latest version of gauge.
  • If installation is failing Upgrade homebrew
  • Gauge plugins are installed under ~/.gauge/plugins directory.


  • The default installation location is /usr/local/.
  • usr/local/bin/ or custom_install_location/bin should be in PATH.
  • Gauge plugins are installed under ~/.gauge/plugins directory.

Plugin installation

  • If plugin installation fails due to a network connection issue, you can manually download the plugin distributable zip and install it using the -f flag.
gauge install plugin_name -f path_to_zip_file


gauge install html-report -f
  • Find the plugin zip files under Releases section of the plugin github repositories. See the gauge plugin list for plugin repositories details.

Plugins directory

Plugins are installed in the .gauge/plugins directory in user’s home. You can check this directory to manually install / uninstall plugins as well as to verify the installed plugins.

The plugin installation directory for various operating systems are listed below.

  • Windows: %APPDATA%\.gauge\plugins
  • Mac OS X: ~/.gauge/plugins
  • Linux: ~/.gauge/plugins

Custom Plugin Install location

By default the plugins are stored at %APPDATA%\gauge\plugins for windows and ~/.gauge/plugins in mac and linux.

To install plugins at different location, set GAUGE_HOME environment variable to the custom location. After setting the GAUGE_HOME env, run the install command. The plugin will get installed at the GAUGE_HOME custom location.


It is advised to use the latest version of gauge and gauge plugins. See our download page for links to latest installation

Validation Errors

[WARN] Validation failed. The following steps have errors

These generally occur if step implementation is not found for a particular step.

  • Ensure the step implementation for the step has been added.
  • The step template marking the step in code is case sensitive and should match the step usage in the spec file.

Compatibility errors

Failed to start a runner. Compatible runner version to 0.0.7 not found
  • The language plugin installed is not compatible with the gauge version installed.
  • Run gauge install language_NAME to install the latest compatible version. See plugin installation for more details

Execution Errors

Error: too many open files
  • This error occurs when the upper limit to open the number of files is too low. To fix the error, increase the upper limit by adding the command ulimit -S -n 2048 to your ~/.profile file and relogin.

Intellij idea plugin

It is advised to use the latest version of gauge and Intellij-gauge.

Intellij idea Errors

Gauge API error

Could not start gauge api: Could not find executable in PATH or GAUGE_ROOT. Gauge is not installed.

This can occur because of following reasons :

  • Gauge is not installed
  • Gauge is installed at custom location and custom_install_location/bin is not in PATH.

To Solve this :

  • If gauge is not installed, install gauge.
  • If gauge is installed at custom location, add custom_install_location/bin to PATH
  • On custom installation location Set GAUGE_ROOT to custom_install_location
  • Restart Intellij

Steps marked as unimplemented

If steps have implementation code and are still marked as unimplemented:

  • Ensure that src/test/java directory is marked as test sources root in the project. Right click on the src/test/java directory and select Mark Directory as -> Test sources root
  • Ensure the project is compiling. Press ctrl/cmd + F9 to build project or select Build -> Make project.
  • Ensure Module SDK is set to a valid JDK under Module settings.
  • Restart Intellij or close and reopen the project.
Check dependencies
For a gauge maven project
  • The gauge-java dependency should be added in the pom.xml
  • Enable auto-import for the project. Under File > Settings > Maven > Importing, mark the checkbox Import Maven projects automatically.
For a simple gauge java project
  • Under Project Settings -> Modules select the gauge module. Under the dependencies tab should be gauge-lib and project-lib.
  • If not present restart Intellij or close and re-open project. They should be added

Project Build failing with compilation error but the Java Files do not mark any errors.

  • The project compilation fails however the java files do not mark any errors in the file.
  • This is a specific issue with Java <= 1.7 on Windows.
  • To resolve set -Duser.home=USER_HOME in the IDEA_INSTALLATIONbinidea.exe.vmoptions file.