Installation Issues

Bun not found

Problem: command not found: bun

Fix: Install Bun:

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

Then restart your terminal or run source ~/.bashrc (or ~/.zshrc).

Dependencies fail to install

Problem: bun install fails with resolution errors.

Fix: Clear the cache and retry:

rm -rf node_modules bun.lockb
bun install

Config file not found

Problem: Dev server starts but shows empty collections or errors about missing config.

Fix: Make sure you’ve created your config file:

cp buddy.config.example.ts buddy.config.ts

Port already in use

Problem: bun dev fails with EADDRINUSE on port 4321.

Fix: Either kill the process using that port or use a different port:

bun dev --port 4322

TypeScript errors on first run

Problem: TypeScript errors about missing types after fresh install.

Fix: The Astro types are generated on first build. Run:

bun run build

Then restart your dev server.

Git merge conflicts after upstream pull

Problem: Conflicts when pulling from upstream after a fork.

Fix: Content files won’t conflict (they’re gitignored). If you see conflicts in buddy.config.example.ts or src/content.config.ts:

1. Review the changes in both versions
2. Keep your customizations while incorporating upstream schema changes
3. Resolve with git add and git merge --continue