Troubleshooting

Generating diagrams relies on Puppeteer (Headless Chrome) and the Mermaid CLI. Differences in operating systems and Node environments can sometimes cause issues.

ARM64 Users (Apple Silicon M1/M2/M3)

Puppeteer may not automatically install a compatible version of Chromium for ARM64 architectures. If you encounter errors on MacOS:

1. Install Chromium via Brew:

   brew install --cask --no-quarantine chromium

2. Verify the path:

   which chromium
   # Output usually: /opt/homebrew/bin/chromium

The generator attempts to automatically detect the Chromium path on ARM64 MacOS. If it fails, or if you are on Linux ARM64, you can force the path using variables:

PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
PUPPETEER_EXECUTABLE_PATH=$(which chromium)

Yarn 3+ (Plug'n'Play)

Yarn 3+ with PnP does not create a standard node_modules/.bin folder, which prevents the generator from finding the mmdc executable.

Solution:

1. Create a shell script named mmdc in your project root:

   #!/bin/bash
   yarn mmdc $@

2. Make it executable:

   chmod +x mmdc

3. Point the generator to this script:

   generator erd {
     provider = "prisma-erd-generator"
     mmdcPath = "./mmdc"
   }

General Debugging

If generation fails silently or produces weird output:

1. Try Markdown Output: Change output to ERD.md. This skips the Puppeteer rendering step. If this works, the issue is likely with Puppeteer/Chrome setup on your machine.

2. Enable Debug Mode: Run with ERD_DEBUG=true.

   ERD_DEBUG=true npx prisma generate

   Check the prisma/debug folder. It will contain:
   • 1-datamodel.json: The parsed Prisma DMMF.
   • 3-mermaid.mmd: The generated Mermaid diagram syntax.

   You can copy the content of 3-mermaid.mmd into the Mermaid Live Editor to verify if the syntax is valid.