Troubleshooting

​

Installation & Setup Issues

​

Setup screen doesn’t appear

1. Superuser already exists (from environment variables or previous setup)
2. Volume persisted from previous deployment

# Stop container
docker-compose down

# Check volume
docker volume inspect primo-data

# If you want to start fresh, delete the volume
docker volume rm primo-data

# Restart
docker-compose up -d

​

Can’t access after deployment

# Check if container is running
docker ps | grep primo

# Check logs
docker logs primo

# Check if port is accessible
curl http://localhost:8080

# Check why it stopped
docker logs primo

# Restart it
docker start primo

sudo lsof -i :8080

​

Runtime Issues

​

”No space left on device” error

# Check Docker disk usage
docker system df

# Clean up unused images/containers
docker system prune -a

# Check host disk space
df -h

# If needed, resize volume or upgrade server

​

Database locked errors

1. Ensure only one Primo container is running:

docker ps | grep primo

2. Restart the container:

docker-compose restart

3. If persists, check for file permissions:

docker exec primo ls -la /app/pb_data

​

Publishing fails or times out

# Check container logs during publish
docker logs -f primo

services:
  primo:
    # ... other config
    deploy:
      resources:
        limits:
          memory: 2G

docker exec primo curl -I https://esm.sh

​

Performance Issues

​

Slow editor loading

• Large blocks with heavy dependencies
• Slow network connection
• Server resource constraints

​

Slow published site

• Test site speed: https://pagespeed.web.dev/
• Check network waterfall in browser DevTools

• Optimize images (compress, use WebP)
• Minimize JavaScript bundle size
• Enable caching headers in reverse proxy
• Use a CDN

​

Docker Issues

​

Image pull fails

1. Check if you’re spelling the image name correctly
2. Check your internet connection
3. Try pulling manually:

docker pull ghcr.io/primocms/primo:latest

​

Permission errors with volume

# Check volume permissions
docker exec primo ls -la /app

# Fix permissions
docker exec primo chown -R 1000:1000 /app/pb_data

​

Container keeps restarting

# Check why it's restarting
docker logs primo --tail=50

# Check restart policy
docker inspect primo | grep -A 5 RestartPolicy

• Application crash (check logs)
• Port already in use
• Out of memory
• Volume mount issues

​

Authentication Issues

​

Can’t sign in

1. Verify email/password are correct
2. Check if account exists:

docker exec primo ./primo admin ls

3. Reset password via PocketBase admin:

• Go to https://your-domain.com/_/
• Sign in with superuser
• Reset user password

​

Locked out of admin

docker exec -it primo ./primo admin create \
  admin@example.com \
  new-secure-password

​

Migration & Upgrade Issues

​

Data loss after upgrade

# Backup pb_data
docker cp primo:/app/pb_data ./backup_$(date +%Y%m%d)

# Then upgrade
docker-compose pull && docker-compose up -d

# Stop container
docker-compose down

# Restore backup
docker cp ./backup_20250101 primo:/app/pb_data

# Restart
docker-compose up -d

​

Blocks not working after upgrade

1. Check release notes for breaking changes
2. Update block code to match new Svelte version
3. Re-publish all sites

​

Network & SSL Issues

​

SSL certificate errors

sudo certbot renew
sudo systemctl restart nginx

​

CORS errors

​

Getting Help

1. Check the logs:

docker logs primo --tail=100 -f

2. Search existing issues:
   • GitHub Issues
3. Ask for help:
   • GitHub Discussions
4. File a bug report:
   • Include: OS, Docker version, Primo version, full error logs
   • Create Issue

​

Next Steps