Type something to search...
to navigateto selectESC to close

Troubleshooting

Common issues and solutions for Astrolock

Troubleshooting

Solutions to common issues when using Astrolock.

Installation Issues

Command Not Found

Problem: astrolock: command not found

Solutions:

  1. You’re not in the Astrolock directory:

    cd /path/to/astrolock
./bin/astrolock version

  2. Astrolock is not in your PATH:

    # Add to PATH (Bash)
echo 'export PATH="/path/to/astrolock-template/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Add to PATH (Zsh)
echo 'export PATH="/path/to/astrolock-template/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

  3. File permissions issue:

    chmod +x /path/to/astrolock-template/bin/astrolock

Node Version Error

Problem: “Unsupported Node.js version” or “Requires Node >= 18”

Solution:

# Check your version
node --version

# Install Node 18 with nvm
nvm install 18
nvm use 18

# Verify
node --version  # Should show v18.x.x

Yarn Not Found

Problem: yarn: command not found

Solution:

npm install -g yarn

# Verify
yarn --version

Permission Denied

Problem: EACCES: permission denied

Solution:

# Don't use sudo! Instead, configure npm properly:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Content Issues

Content Not Showing on Site

Problem: Created content doesn’t appear on the website

Checklist:

  1. Is it published?

    # Check draft status
astrolock list <collection>

# Publish if needed
astrolock publish <collection>/<slug>

  2. Did you rebuild?

    astrolock build

  3. Is the media file present?

    # Check if file exists
ls public/audio/content/<collection>/<slug>.mp3
ls public/images/content/<collection>/<slug>.jpg

  4. Filename match?

    • Markdown: my-mix.md
    • Media: my-mix.mp3 (must match exactly!)

Can’t Find My Content

Problem: Don’t know where content is located

Solution:

# List all content
astrolock list

# List specific collection
astrolock list mixes

# Find file location
find src/content -name "*my-mix*"

Content locations:

  • Markdown: src/content/<collection>/<slug>.md
  • Audio: public/audio/content/<collection>/<slug>.mp3
  • Images: public/images/content/<collection>/<slug>.jpg
  • Video: public/video/content/<collection>/<slug>.mp4

Media File Not Loading

Problem: Audio/image/video doesn’t play or show

Solutions:

  1. Check file exists:

    ls -lh public/audio/content/mixes/my-mix.mp3

  2. Check filename matches:

    • Markdown slug: my-mix.md
    • Media file: my-mix.mp3
    • They must match exactly (case-sensitive!)

  3. Check file format:

    # Verify file type
file public/audio/content/mixes/my-mix.mp3

  4. Check file size:

    # If file is 0 bytes or corrupt
ls -lh public/audio/content/mixes/my-mix.mp3

Categories or Tags Not Showing

Problem: Categories/tags don’t appear on site

Solution:

Check your frontmatter syntax:

# ✅ Correct - Use YAML list format
categories:
  - house
  - techno

tags:
  - vinyl
  - 2025

# ❌ Wrong - Don't use comma-separated strings
categories: house, techno
tags: vinyl, 2025

Build Issues

Build Fails

Problem: astrolock build fails with errors

Common causes:

  1. Invalid YAML in frontmatter: Check your content files for YAML syntax errors in the frontmatter. Try building to see specific validation errors: astrolock build

  2. Missing collections:

    # Check config
cat .astrolock/astrolock.yaml

  3. Broken links in markdown:

    • Check for [text](broken-link.md)
    • Fix or remove broken links

  4. Missing dependencies:

    yarn install

Port Already in Use

Problem: “Port 4321 is already in use”

Solutions:

  1. Kill existing process:

    # Find process using port 4321
lsof -i :4321

# Kill it (replace PID with actual number)
kill -9 <PID>

  2. Use different port (coming soon):

    astrolock write --port 3000

Out of Memory

Problem: “JavaScript heap out of memory”

Solution:

# Increase Node memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
astrolock build

Configuration Issues

Invalid Configuration

Problem: “Invalid configuration” or YAML parsing errors

Solutions:

  1. Validate YAML syntax:

    # Use yq or yamllint
yq eval .astrolock/astrolock.yaml

# Or online validator
# Copy/paste to https://www.yamllint.com/

  2. Common YAML mistakes:

    # ❌ Wrong indentation
collections:
mixes:
  displayName: "Mixes"

# ✅ Correct indentation (2 spaces)
collections:
  mixes:
    displayName: "Mixes"

# ❌ Missing quotes for special characters
title: My Site: The Best

# ✅ Use quotes
title: "My Site: The Best"

  3. Reset to defaults:

    # Backup current config
cp .astrolock/astrolock.yaml .astrolock/astrolock.yaml.backup

# Reinitialize
astrolock init

Collection Not Found

Problem: “Collection ‘mixes’ not found”

Solution:

  1. Check collection exists:

    cat .astrolock/astrolock.yaml | grep -A 5 "collections:"

  2. Add missing collection:

    collections:
  mixes:
    displayName: "DJ Mixes"
    contentType: "audio"
    defaults:
      contentExtension: "mp3"

  3. Restart dev server:

    # Stop with Ctrl+C
astrolock write

Import Issues

Rekordbox Import Fails

Problem: astrolock import rekordbox doesn’t work

Solutions:

  1. Check prerequisites:

    # Verify lame and ffmpeg installed
which lame
which ffmpeg

# Install if missing (macOS)
brew install lame ffmpeg

  2. Check import folder:

    # Verify WAV files exist
ls ~/Rekordbox/Recordings/*.wav

  3. Check CUE files:

    • Must have same name as WAV
    • my-mix.wav → my-mix.cue

  4. Configuration:

    # Check config
cat .astrolock/rekordbox.yaml

Slow Encoding

Problem: MP3 encoding takes very long

Expected: A 60-minute mix takes 2-5 minutes to encode at 320kbps.

If slower:

  • Check CPU usage
  • Close other programs
  • Use faster storage (SSD vs HDD)

Deployment Issues

AWS Deploy Fails

Problem: astrolock deploy fails

Solutions:

  1. Check AWS credentials:

    aws sts get-caller-identity --profile <profile-name>

  2. Check deployment config:

    # In .astrolock/astrolock.yaml
deploy:
  targets:
    production:
      platform: "aws"
      aws:
        profile: "your-profile"
        bucket: "your-bucket"
        region: "us-east-1"

  3. Build first:

    astrolock build
astrolock deploy production --execute

  4. Check bucket exists:

    aws s3 ls s3://your-bucket --profile your-profile

CloudFront Not Invalidating

Problem: Changes don’t appear after deploy

Solution:

# Manual CloudFront invalidation
aws cloudfront create-invalidation \
  --distribution-id E123ABC \
  --paths "/*" \
  --profile your-profile

Performance Issues

Slow Dev Server

Problem: astrolock write is slow to start or reload

Solutions:

  1. Clear cache:

    rm -rf .astro node_modules/.cache
yarn install

  2. Reduce content:

    • Unpublish old drafts
    • Remove unused media files

  3. Check system resources:

    • Close other applications
    • Check disk space: df -h
    • Check memory: free -h (Linux) or Activity Monitor (macOS)

Slow Build Time

Problem: astrolock build takes too long

Solutions:

  1. Optimize images:

    # Compress images before adding
# macOS: use ImageOptim
# Linux: use optipng or jpegoptim

  2. Clean build cache:

    rm -rf dist .astro
astrolock build

  3. Check content size:

    # Count content files
find src/content -type f | wc -l

# Check media file sizes
du -sh public/*

Git Issues

Accidentally Deleted Content

Problem: Deleted content file by mistake

Solution:

# Restore from git
git checkout HEAD src/content/mixes/my-mix.md

# Or restore from last commit
git restore src/content/mixes/my-mix.md

# See what was deleted
git log -- src/content/mixes/my-mix.md

Large Files in Git

Problem: Git repository is huge

Solution:

# Exclude media files from git
echo "public/audio/" >> .gitignore
echo "public/images/" >> .gitignore
echo "public/video/" >> .gitignore
echo "dist/" >> .gitignore

# Remove already committed files
git rm --cached -r public/audio/
git commit -m "Remove media files from git"

Error Messages

”Cannot find module”

Problem: Error: Cannot find module 'some-package'

Solution:

# Reinstall dependencies
rm -rf node_modules yarn.lock
yarn install

“Port already in use”

Problem: Error: listen EADDRINUSE: address already in use :::4321

Solution:

# Find and kill process
lsof -i :4321
kill -9 <PID>

“Disk quota exceeded”

Problem: ENOSPC: no space left on device

Solution:

# Check disk space
df -h

# Clean up
astrolock clean
rm -rf dist node_modules/.cache

Getting More Help

Diagnostic Information

When reporting issues, include:

# System info
astrolock version
node --version
yarn --version
uname -a

# Error output
astrolock build 2>&1 | tee build-error.log

Where to Get Help

  • Documentation: User Guide
  • Command Help: astrolock --help
  • GitHub Issues: Report bugs or ask questions
  • Community: (Coming soon)

Before Reporting an Issue

  1. ✅ Check this troubleshooting guide
  2. ✅ Search existing GitHub issues
  3. ✅ Try with a clean install
  4. ✅ Include diagnostic information
  5. ✅ Provide steps to reproduce

See also: