Troubleshooting / common issues

👍
Asking for help
See Getting Help. We would love to help!
If you are confused by something, likely someone else will run into the same issue. It is helpful for us to know what is going wrong so that we can improve Pants and improve this documentation.

Debug tip: enable stack traces and increase logging

Pants defaults to not displaying the full stack trace when it encounters an error. Pants also defaults to logging at the info level.

When you encounter an exception, it can help to use the global options --print-exception-stacktraces and -ldebug, like this:

<<pantscmd>> --print-exception-stacktrace -ldebug

Once you have this stack trace, we recommend copying it into Pastebin or a GitHub Gist, then opening a GitHub issue or posting on Slack. Someone from the Pants team would be happy to help. See Getting Help.

"Too many open files" error

You may encounter this error when running Pants:

$ ./pants cloc helloworld/greet

ERROR: Could not initialize store for process cache: "Error making env for store at \"/Users/pantsbuild/.cache/pants/lmdb_store/processes/2\": Too many open files"

(Use --print-exception-stacktrace to see more error details.)

This sometimes happens because Pants uses lots of file handles to read and write to its cache at ~/.cache/pants/lmdb_store; often, this is more than your system's default.

This can be fixed by setting ulimit -n 10000. (10,000 should work in all cases, but feel free to lower or increase this number as desired.)

📘
Tip: permanently configuring ulimit -n
We recommend permanently setting this by either:

Adding ulimit -n 10000 to your ./pants script.

Using a tool like Direnv to run ulimit -n 10000 everytime the project is loaded.

Adding ulimit -n 10000 to your global .bashrc or equivalent.

The first two approaches have the benefit that they will be checked into version control, so every developer at your organization can use the same setting.

🚧
macOS users: avoid ulimit unlimited
Contrary to the name, this will not fix the issue. You must use ulimit -n instead.

"Out of space" error: set an alternative tmpdir

It may be necessary to explicitly set the directory Pants uses as a temporary directory. For example, if the system default temporary directory is a small partition, you may exhaust that temp space.

Use the global option local_execution_root_dir to change the tmpdir used by Pants.

[GLOBAL]
local_execution_root_dir = "/mnt/large-partition/tmpdir"

"No space left on device" error while watching files

On Linux, Pants uses inotify to watch all files and directories related to any particular build. Some systems have limits configured for the maximum number of files watched. To adjust the limit on file watches, you can run:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

"Double requirement given" error

This is an error from pip, and it means that the same 3rdparty Python requirement, with different version constraints, appears in your dependencies. You can use one of these commands to list the dependencies and find the conflicting requirements:

$ # List all targets the specified targets depend on.
$ ./pants dependencies --transitive <targets>
$
$ # List all files the specified targets depend on.
$ ./pants filedeps --transitive <targets>

Pants cannot find a file in your project

Pants may complain that it cannot find a file or directory, but the file does indeed exist.

Almost always, this error happens because of the option pants_ignore in the [GLOBAL] scope. By default, Pants will read your top-level .gitignore file to populate pants_ignore, along with ignoring dist/ and any top-level files/directories starting with ..

To override something included in your .gitignore, add a new value to pants_ignore and prefix it with !, like the below. pants_ignore uses the same syntax as gitignore.

[GLOBAL]
pants_ignore.add = ["!folder/"]

Alternatively, you can stop populating pants_ignore from your .gitignore by setting pants_ignore_use_gitignore = false in the [GLOBAL] scope.

Running Pants with M1 Macs / Apple Silicon

Pants 1.30.x can only be run with Python 3.6-3.8, but Apple Silicon is not natively supported until version 3.9. One way to bypass this problem is to build python 3.8 under x86_64 via homebrew. You will need to create a separate brew installation and install the [email protected] formula.

$ arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

$ arch -x86_64 brew install [email protected]

N.B. This will install python into /usr/local/opt/[email protected]/bin/python3

Having this on $PATH, it should be possible to run pants as arm_64.