Troubleshooting common Vulpy issues

Fix common problems when running Vulpy Commerce: ownership drift, AWS IMDS, data directories, multiple shops, going live, and credentials resets.

When something goes wrong with your Vulpy Commerce install, use the commands and checks below to get back on track. Each entry includes the exact symptom and the fix.

Before you grep logs, ask Fox. Fox already knows most of these symptoms, can run the diagnostic commands, and will tell you the fix in context.

Try prompts like:

• “Diagnose why Fox won’t start.”
• “Why is env golive live refusing?”
• “Run pnpm vulpy hermes doctor and explain the result.”

Hermes ownership drift

Fox (Hermes) runs a pruned workspace chown on startup, but ownership can still drift after edits or restores. If Fox fails to start or file permissions look wrong, run the repair command from the host:

pnpm vulpy hermes repair-ownership

AWS IMDS blocked

On AWS EC2 or Lightsail, Vulpy blocks instance metadata access by default so Fox cannot use the VM IAM role. If you need Bedrock or another service that relies on IMDS, either set an explicit provider API key or opt out by setting this variable before starting Fox:

VULPY_IMDS_LOCK=0

Check the current lock status with pnpm vulpy hermes doctor.

Postgres, Redis, or Matomo on NTFS/exFAT

If your Docker data lives on an NTFS or exFAT mount (for example, /mnt/data), Postgres, Redis, and Matomo auto-fallback to ~/.local/share/<project>/…. To override those paths, set the data directory variables in your .env file:

POSTGRES_DATA_DIR=/path/to/postgres
REDIS_DATA_DIR=/path/to/redis
MATOMO_DATA_DIR=/path/to/matomo
MATOMO_DB_DATA_DIR=/path/to/matomo-db

Multiple shops on one host

To run more than one Vulpy shop on the same machine, make sure each project uses a different Compose project name. The default is the folder name. You can override it in .env:

COMPOSE_PROJECT_NAME=my-second-shop

golive refuses to complete

pnpm vulpy env golive live will refuse if Matomo is not running. Matomo is optional in dev but required for live. Start Matomo first, then retry:

pnpm vulpy env up live
pnpm vulpy env golive live

Reset admin credentials

If you forget the shared admin password for Medusa, Payload, Matomo, or the Hermes UI, reset it from the host:

pnpm vulpy user reset

Health check

To verify the shop, Medusa, Payload, and Fox basic auth are healthy, run:

pnpm vulpy verify

For Fox-specific diagnostics (Tailscale, egress lock, and IMDS on AWS), run:

pnpm vulpy hermes doctor