CLI Troubleshooting

Solutions for common CLI issues.

Network Errors

If the template download fails:

# Test GitHub access
curl https://github.com/southwellmedia/velocity

For slow connections, the download may timeout. Try:

# Increase timeout
npm create velocity-astro@latest my-site --timeout=60000

The CLI prompts before overwriting existing directories:

? Directory "my-site" already exists. Overwrite? (y/N)

Options:

On Unix systems, you may need execute permissions:

chmod +x node_modules/.bin/create-velocity-astro

If automatic installation fails:

cd my-site
npm install  # or pnpm install / yarn / bun install

Velocity requires Node.js 18.0.0 or higher:

# Check your version
node --version

# Update with nvm
nvm install 18
nvm use 18

The CLI auto-detects your package manager. If detection fails:

# Specify explicitly
cd my-site
pnpm install  # or npm/yarn/bun

If components are missing after scaffold:

# Include all components
npm create velocity-astro@latest my-site --components=all

If components have import errors:

# Regenerate types
cd my-site
npm run astro sync

If locale routes aren’t working:

Add missing translations in src/config/i18n.ts:

export const translations = {
  en: { /* ... */ },
  es: { /* ... */ },
  // Add your new locale
  de: { /* ... */ },
};

If git initialization fails:

cd my-site
git init
git add .
git commit -m "Initial commit"

Install git from git-scm.com.

If you’re still stuck:

Check the GitHub Issues
Search for your error message
Open a new issue with:
- Node.js version
- Package manager used
- Full error message
- Steps to reproduce