> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  **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."
</Tip>

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    pnpm vulpy hermes repair-ownership
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    VULPY_IMDS_LOCK=0
    ```

    Check the current lock status with `pnpm vulpy hermes doctor`.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    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
    ```
  </Accordion>

  <Accordion title="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`:

    ```bash theme={null}
    COMPOSE_PROJECT_NAME=my-second-shop
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    pnpm vulpy env up live
    pnpm vulpy env golive live
    ```
  </Accordion>

  <Accordion title="Reset admin credentials">
    If you forget the shared admin password for Medusa, Payload, Matomo, or the Hermes UI, reset it from the host:

    ```bash theme={null}
    pnpm vulpy user reset
    ```
  </Accordion>

  <Accordion title="Health check">
    To verify the shop, Medusa, Payload, and Fox basic auth are healthy, run:

    ```bash theme={null}
    pnpm vulpy verify
    ```

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

    ```bash theme={null}
    pnpm vulpy hermes doctor
    ```
  </Accordion>
</AccordionGroup>