Skip to content

Troubleshooting

This page contains common issues and (hopefully) solutions for Control Plane development. Where possible, full error messages are included to make it easy to search for your particular issue.

Pip Version Error

When running Pants, you may see an error like this:

No supported version of Pip is compatible with the given targets:

Pants uses Pex to create a virtual environment for running tests. Pex is quite picky about which versions of Pip it's compatible with. If you haven't seen this before, ir's likely you've recently upgraded the version of Pip you're using.

To fix this, you can explicitly install a version of Pip that is compatible with the version of Pex being used by Pants, e.g.:

pip install pip==24.3.1

Rust/Cargo

Some dependencies require Rust to be built from source.

Install Rust from https://rustup.rs/.

ModuleNotFoundError: No module named ''

Make sure you've added a BUILD file to the package you're trying to import from. Run pants tailor :: -. to generate any missing BUILD files.

IntrinsicError: Failed to obtain version from local Docker: error trying to connect: No such file or directory (os error 2)

When using docker_environment (which we do for Docker image packaging):

if you are using Docker Desktop, make sure the option Enable default Docker socket is enabled, you can find it in Docker Desktop Settings > Advanced panel. That option tells Docker to create a socket at /var/run/docker.sock which Pants can use to communicate with Docker.

If this is already enabled, try disabling (apply and restart) and re-enabling it.

Hippodrome (Running Locally)

The hippodrome orchestrator has its own comprehensive troubleshooting guide. For issues when running pants run //components/hippodrome/hippodrome/cli.py -- start, see the Hippodrome Troubleshooting Guide.

Common hippodrome issues include:

Port Already in Use

OSError: [Errno 48] Address already in use

One of the required ports (9000, 9001, 9002, or 9008) is in use by another process. Find and kill it:

lsof -ti :9001 | xargs kill -9

Services Stuck Waiting for Pants

Another pants invocation is running. Will wait up to 60.0 seconds...

Run hippodrome with PANTS_CONCURRENT=True:

PANTS_CONCURRENT=True pants run //components/hippodrome/hippodrome/cli.py -- start

Controller Django Module Not Found

ModuleNotFoundError: No module named 'config'

The controller uses a local venv instead of pants. The orchestrator creates it automatically, but you can recreate it manually:

cd components/controller
rm -rf .venv
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Console Fails to Start

Console is non-blocking - other services continue if it fails. Common causes:

  • Missing Node.js/npm: Install from https://nodejs.org/
  • npm ci fails: Try cd components/console && rm -rf node_modules && npm install

E-commerce Services Not Starting

E-commerce services (admin_server, search_proxy) require the ecom profile:

PANTS_CONCURRENT=True pants run //components/hippodrome/hippodrome/cli.py -- start --profile ecom

Available profiles: core (default), ecom, full

Wrong DynamoDB Tables

Table prefix defaults to dev-{git-branch}-. Check the startup message or use --table-prefix:

PANTS_CONCURRENT=True pants run //components/hippodrome/hippodrome/cli.py -- start --table-prefix my-feature-

EventBridge Webhook Not Routing Events

If events sent to /webhook/eventbridge return "ignored" status, check:

  • The detail-type field uses the correct prefix (EcomIndexSettings.* or Merchandising.*)
  • The field name is detail-type (with hyphen), not detailType or detail_type
  • See the Hippodrome Troubleshooting Guide for more EventBridge issues