Troubleshooting

Installation Issues

Puppeteer Install Fails (Local)

Error: Error: Cannot find module 'puppeteer' or installation hangs

Cause: Missing system dependencies or network issues

Solution:

# Install Chrome dependencies (Linux/WSL)
sudo apt-get update
sudo apt-get install -y \
  libx11-6 libxcomposite1 libxcursor1 libxdamage1 libxext6 \
  libxfixes3 libxi6 libxtst6 libnss3 libglib2.0-0 libgtk-3-0t64 \
  libasound2t64 libxrandr2 libpangocairo-1.0-0 libatk1.0-0 \
  libatk-bridge2.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 \
  libgdk-pixbuf2.0-0

Note

On macOS, Puppeteer usually works out of the box. On Windows, ensure you have the latest Visual C++ Redistributable installed.

Bun Not Found (Local)

Error: bash: bun: command not found

Solution:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Or with npm
npm install -g bun

Verify installation:

bun --version

Build Command Issues (Local)

Chrome Not Found (PDF Generation)

Error: Failed to launch the browser process or Chrome not found

Cause: Puppeteer can’t find Chrome/Chromium

Solution:

1. Install Chrome dependencies (see Puppeteer section above)
2. Set Puppeteer skip download in .env:

PUPPETEER_SKIP_DOWNLOAD=true

3. Ensure system Chrome/Chromium is installed:

# Ubuntu/Debian
sudo apt-get install chromium-browser

# macOS
brew install --cask google-chrome

DEVSYNC.json Validation Errors

Error: Invalid DEVSYNC.json structure or Missing required profile field

Cause: Schema validation failed

Solution:

1. Check that all required fields are present:

   • defaultLang
   • site
   • name
   • img
   • githubUserName

2. Verify JSON syntax (no trailing commas, proper quotes)

3. Check field types match expected values

Example invalid vs valid:

// ❌ Invalid - missing quotes
{
  name: John Doe,  // Should be "name": "John Doe"
  "site": https://example.com  // Should be "https://example.com"
}

// ✅ Valid
{
  "name": "John Doe",
  "site": "https://example.com"
}

PNPM create-template does not work

pnpm has strict security rules for script execution that might prevent create-template from working out of the box. I recommend using bunx instead. Since bunx only uses built-in Bun features to copy the @core folder, there are no security concerns.

Git Issues

Permission Denied When Pushing

Error: remote: Permission denied or fatal: could not read Username

Cause: Missing or incorrect GitHub credentials

Solution:

For GitHub Actions:

permissions:
  contents: write

For local Git:

# Check remote URL
git remote -v

# Re-authenticate
git credential-cache exit
git push

Template Issues

Template Not Found

Error: Template DEVSYNC.json not found or Failed to clone repository

Cause: Invalid template URL or repository doesn’t exist

Solution:

1. Verify template URL is correct:

# Should be: https://github.com/[owner]/[repo]
bunx @jannael/devsync init --template @jannael/my-template

2. Check repository exists and is public

3. Use default template if unsure:

bunx @jannael/devsync init

PDF Generation Issues

PDF Not Generated

Error: PDF file missing from output

Cause: HTML to PDF conversion failed

Solution:

1. Check that package.json has correct path:

{
  "devsync": {
    "pathToCompiledCV": "./dist/[lang]/cv/index.html"
  }
}

2. Verify HTML file exists at that path

3. Check build command actually generates the HTML

PDF Quality Issues

Problem: PDF looks cut off or misformatted

Solution:

1. Ensure HTML has proper viewport meta tag
2. Check CSS doesn’t have fixed widths that exceed page size
3. Test PDF generation locally first

GitHub Actions Issues

Workflow Not Triggering

Problem: Push to DEVSYNC.json but workflow doesn’t run

Solution:

1. Check Actions tab - workflow might be disabled
2. Verify DEVSYNC.json is in root (not subdirectory)
3. Check workflow file path: .github/workflows/*.yml
4. Verify YAML syntax:

on:
  push:
    paths:
      - 'DEVSYNC.json'  # Exact match required

Job Fails on Ubuntu

Error: Various errors on ubuntu-latest runner

Solution:

Add all required dependencies:

- name: Install dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y libx11-6 libnss3 libgtk-3-0t64 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxtst6 libxrandr2 libpangocairo-1.0-0 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgdk-pixbuf2.0-0 libasound2t64

Performance Issues

Slow Build Times

Problem: Build takes >5 minutes

Solution:

1. Cache dependencies:

- name: Cache Bun dependencies
  uses: actions/cache@v4
  with:
    path: ~/.bun/install/cache
    key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}

2. Use specific Bun version instead of latest

3. Reduce image sizes in DEVSYNC.json

Common Error Messages

Error	Cause	Solution
ENOENT: no such file or directory	File path doesn’t exist	Check paths in config
EACCES: permission denied	File permissions issue	Check file permissions
ETIMEDOUT	Network timeout	Check network, retry
Invalid URL	Malformed URL in config	Fix URL format
ZodError	Validation failed	Check field types/values

Getting Help

If your issue isn’t listed here:

1. Check existing GitHub Issues
2. Review Configuration Reference
3. Check GitHub Actions Guide
4. Create a new issue with:
   • Error message
   • Your DEVSYNC.json (remove sensitive data)
   • Steps to reproduce