Troubleshooting Quartz Publishing

Troubleshooting Quartz Publishing

Solutions for common Quartz publishing problems plus debugging tips.

Table of Contents

1. Quick Diagnostics
2. Build Problems
3. Preview Problems
4. Publishing Problems
5. Sync Problems
6. Alfred Problems
7. Debugging Checklist

---

Quick Diagnostics

Run these commands first to identify the problem:

# Check Quartz builds
cd ~/Developer/mementropy-quartz
npx quartz build

# Check log files
cat /tmp/quartz-publish.log
cat /tmp/quartz-preview.log

# Check git status
git status

# Check Node.js
node --version    # Should be 18+
npx --version

# Check if preview server running
lsof -i :8080

---

Build Problems

Problem: “Cannot find module” Error

Symptoms:

Error: Cannot find module '@jackyzha0/quartz'

Solution:

cd ~/Developer/mementropy-quartz
npm install

Problem: “EACCES permission denied”

Symptoms:

EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solution:

# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

# Or use nvm instead
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Problem: Frontmatter Parsing Error

Symptoms:

Error parsing frontmatter in content/some-file.md

Solution:

1. Open the mentioned file
2. Check YAML syntax:
   • Colons in values need quotes: title: "My Title: Subtitle"
   • Lists need proper indentation
   • No tabs, only spaces

# Wrong
title: My Title: With Colon

# Correct
title: "My Title: With Colon"

Problem: “Could not resolve entry module”

Symptoms:

Could not resolve entry module (content/index.md)

Solution: Quartz needs an index.md in content root:

# Check if index exists
ls ~/Developer/mementropy-quartz/content/index.md

# If missing, create it
echo "---
title: Home
---

Welcome to my site." > ~/Developer/mementropy-quartz/content/index.md

---

Preview Problems

Problem: Port 8080 Already in Use

Symptoms:

Error: listen EADDRINUSE: address already in use :::8080

Solution:

# Find process using port
lsof -i :8080

# Kill it
lsof -i :8080 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Or kill all Quartz processes
pkill -f "quartz"

# Remove stale PID file
rm -f /tmp/quartz-preview.pid

Problem: Preview Shows Old Content

Symptoms:

• Made changes but preview doesn’t update
• Browser shows cached version

Solution:

# Stop current server
pkill -f "quartz"

# Clear Quartz cache
rm -rf ~/Developer/mementropy-quartz/.quartz-cache

# Restart preview
cd ~/Developer/mementropy-quartz
npx quartz build --serve

Also try hard refresh in browser: Cmd+Shift+R

Problem: Preview Command Hangs

Symptoms:

• Alfred shows triggered but nothing happens
• No browser opens

Solution:

# Check log
cat /tmp/quartz-preview.log

# Try manual build
cd ~/Developer/mementropy-quartz
npx quartz build --serve

If manual build works but Alfred doesn’t, check PATH:

# In Alfred script, use full paths:
/usr/local/bin/npx quartz build --serve

# Find your npx path:
which npx

---

Publishing Problems

Problem: “Permission denied” on Script

Symptoms:

./scripts/publish.sh: Permission denied

Solution:

chmod +x ~/Developer/mementropy-quartz/scripts/publish.sh

Problem: Git Push Asks for Password

Symptoms:

fatal: could not read Password for 'https://github.com'

Solution: Switch to SSH authentication:

# Generate SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy public key
cat ~/.ssh/id_ed25519.pub | pbcopy

# Add to GitHub: Settings → SSH Keys → New SSH Key

# Update remote URL
cd ~/Developer/mementropy-quartz
git remote set-url origin git@github.com:USERNAME/repo.git

# Test
ssh -T git@github.com

Problem: “Nothing to commit”

Symptoms:

• Publish says no changes
• But you edited files

Solution: Check if changes are in the right place:

cd ~/Developer/mementropy-quartz

# Check git status
git status

# Are content changes showing?
git diff content/

# If content/ is a symlink, check the actual files
ls -la content/

If using symlink, changes might be detected differently. Adjust publish.sh:

# In publish.sh, force-add content
git add -A content/

Problem: GitHub Actions Fails

Symptoms:

• Push succeeds but deployment fails
• Red X on GitHub Actions

Solution:

1. Visit: https://github.com/USERNAME/repo/actions
2. Click failed run
3. Expand failed step to see error
4. Common fixes:
   • Check quartz.config.ts has correct baseUrl
   • Verify package.json has all dependencies
   • Check workflow file (.github/workflows/deploy.yml)

---

Sync Problems

Problem: Files Not Syncing to Mac Mini

Symptoms:

• Edit on iPad
• Mac mini doesn’t see changes
• Publish uses old content

Diagnostics:

# Check file timestamps on Mac mini
ls -lt ~/Obsidian/Ingenium/mementropy-site/ | head -5

# If timestamps are old, sync isn't working

Solutions by Sync Service:

Obsidian Sync

# On Mac mini, open Obsidian once
# Check Settings → Sync → Status
# Should show "Synced" or sync in progress
# Can close Obsidian after sync completes

iCloud Drive

# Check iCloud is active
brctl status

# Restart iCloud daemon
killall bird

# Wait 30 seconds, check files again

Test Sync Manually

# Create test file on editing device
# In Obsidian: New file → "sync-test-[date].md"

# Wait 60 seconds

# On Mac mini:
ls ~/Obsidian/Ingenium/mementropy-site/sync-test*.md

Problem: Vault Path Mismatch

Symptoms:

• Quartz can’t find content
• Empty or missing pages

Solution: Verify paths match:

# Check where Quartz looks for content
ls -la ~/Developer/mementropy-quartz/content/

# If symlink, where does it point?
readlink ~/Developer/mementropy-quartz/content/

# Check actual vault location
ls ~/Obsidian/Ingenium/mementropy-site/

Update symlink if needed:

cd ~/Developer/mementropy-quartz
rm content  # Remove old symlink
ln -s ~/Obsidian/Ingenium/mementropy-site content

---

Alfred Problems

Problem: Keyword Not Recognized

Symptoms:

• Type publish in Alfred
• Nothing appears

Solutions:

1. Check workflow enabled:

   • Alfred Preferences → Workflows
   • Verify checkmark next to workflow

2. Rebuild Alfred cache:

   • Alfred Preferences → Advanced
   • Click “Clear Application Cache”
   • Click “Clear Keyword Cache”
   • Restart Alfred

3. Check for conflicts:

   • Search for “publish” in workflows
   • Multiple workflows using same keyword?

Problem: Notifications Don’t Appear

Solutions:

1. Check macOS settings:

   • System Settings → Notifications → Alfred
   • Allow Notifications: ON
   • Style: Alerts or Banners

2. Check Focus mode:

   • Turn off Do Not Disturb

3. Test notifications:

   osascript -e 'display notification "Test" with title "Alfred"'

Problem: Alfred Remote Can’t Connect

Solutions:

1. iCloud method:

   • Sign out on both devices
   • Sign back in with SAME Apple ID
   • Wait 2-3 minutes for sync

2. Local network method:

   • Both devices on same WiFi?
   • Check Mac firewall allows Alfred

3. Restart Alfred:

   • Quit Alfred completely (Cmd+Q)
   • Relaunch from Applications

---

Debugging Checklist

When something breaks, work through systematically:

Basic Checks

• npx quartz build runs without errors
• cat /tmp/quartz-publish.log shows recent activity
• git status shows expected changes
• Script has execute permission: ls -la scripts/publish.sh

For Preview Issues

• Port 8080 is free: lsof -i :8080
• Node.js version 18+: node --version
• Manual build works: npx quartz build --serve

For Publishing Issues

• Git can push: git push --dry-run
• SSH works: ssh -T git@github.com
• Changes exist: git diff content/

For Remote Publishing

• File sync working (check timestamps)
• Alfred Remote connected (green dot)
• Mac mini awake (check Energy settings)
• Local workflows work before testing remote

For Deployment Issues

• GitHub Actions passed (check repo Actions tab)
• baseUrl correct in quartz.config.ts
• Wait 2-3 minutes after push

---

Log File Reference

File	Contains
/tmp/quartz-preview.log	Preview server output
/tmp/quartz-publish.log	Publish script output
/tmp/quartz-preview.pid	Preview server process ID

Useful Commands

# View logs
cat /tmp/quartz-publish.log
tail -f /tmp/quartz-preview.log  # Live view

# Clear logs
rm /tmp/quartz-*.log

# Check Quartz version
cd ~/Developer/mementropy-quartz
npx quartz --version

# Full rebuild
rm -rf .quartz-cache public/
npx quartz build

---

Getting Help

If you’re still stuck:

1. Check Quartz docs: quartz.jzhao.xyz
2. Search issues: github.com/jackyzha0/quartz/issues
3. Quartz Discord: Link in Quartz repo

---

Related

• Alfred Workflows for Quartz - Setup guide
• Remote Publishing - iPhone/iPad control

---

Last updated: 2025-01-13