Bootspring
HomeGet Started

Troubleshooting

Solutions to common issues when using Bootspring.

Installation Issues#

"Command not found: bootspring"#

The global npm bin directory isn't in your PATH.

Solution:

1# Find npm global bin path 2npm config get prefix 3 4# Add to PATH in ~/.bashrc or ~/.zshrc 5export PATH="$(npm config get prefix)/bin:$PATH" 6 7# Reload shell 8source ~/.bashrc # or ~/.zshrc

Alternative - use npx:

npx bootspring init npx bootspring generate

"Permission denied" during install#

npm doesn't have permission to install globally.

Solution (macOS/Linux):

1# Option 1: Fix npm permissions 2mkdir -p ~/.npm-global 3npm config set prefix '~/.npm-global' 4echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc 5source ~/.bashrc 6npm install -g bootspring 7 8# Option 2: Use sudo (not recommended) 9sudo npm install -g bootspring

"Node version not supported"#

Bootspring requires Node.js 18+.

Solution:

1# Check current version 2node --version 3 4# Install Node.js 20 LTS using nvm 5nvm install 20 6nvm use 20 7 8# Or download from nodejs.org

MCP Connection Issues#

"MCP server not connecting"#

Your AI assistant can't connect to the Bootspring MCP server.

Solutions:

  1. Check .mcp.json exists:
ls -la .mcp.json
  1. Verify .mcp.json content:
1{ 2 "mcpServers": { 3 "bootspring": { 4 "command": "npx", 5 "args": ["-y", "bootspring", "serve"] 6 } 7 } 8}

  1. Restart your AI assistant (Claude Code, Cursor, etc.)

  2. Check if server starts manually:

npx bootspring serve
  1. Verify Node.js is accessible:
which node which npx

"Bootspring tools not appearing"#

The MCP tools aren't showing in your AI assistant.

Solutions:

  1. Restart your AI assistant completely

  2. Check MCP configuration location:

    • Claude Code: .mcp.json in project root
    • Cursor: ~/.cursor/mcp.json
    • Continue: Check Continue settings

  3. Verify with doctor:

bootspring doctor
  1. Check server logs:
BOOTSPRING_DEBUG=true npx bootspring serve

"Connection timeout"#

MCP server times out during requests.

Solutions:

  1. Increase timeout in config:
1// bootspring.config.js 2module.exports = { 3 server: { 4 timeout: 60000, // 60 seconds 5 }, 6};
  1. Check network connectivity:
ping api.bootspring.com
  1. Verify API key is valid:
bootspring auth status

Authentication Issues#

"Invalid API key"#

Your API key is rejected.

Solutions:

  1. Check key format:

    • Should start with bsk_
    • Example: bsk_prod_abc123xyz

  2. Verify key in dashboard:

    • Visit bootspring.com/dashboard/keys
    • Check if key is active

  3. Regenerate key if needed:

    • Dashboard → API Keys → Create Key

  4. Set key in environment:

export BOOTSPRING_API_KEY=bsk_prod_your_key_here

"Device limit reached"#

You've reached the maximum devices for your tier.

Solutions:

  1. Check device count:
bootspring auth status

  1. Remove unused devices:

    • Dashboard → Devices → Disconnect

  2. Upgrade your plan for more devices:

    • Free: 2 devices
    • Pro: 5 devices
    • Team: 10 devices

"Authentication required"#

Commands fail because you're not logged in.

Solution:

bootspring auth login

This opens your browser for authentication and project selection.

"Directory not linked to a project"#

The current directory doesn't have a .bootspring.json file.

Solution:

# Run login to link this directory to a project bootspring auth login # → Opens browser → Select/create project → Creates .bootspring.json

Or if you're already authenticated:

# Switch to link this directory to a project bootspring switch my-project

"Wrong project context"#

Commands are using a different project than expected.

Solutions:

  1. Check current project:
bootspring auth status # Shows: Project: my-app (from .bootspring.json)
  1. Switch to correct project:
bootspring switch correct-project

  1. Check for conflicting configs:

    • .bootspring.json in current directory
    • bootspring.config.js with project settings
    • Session state in ~/.bootspring/

  2. Clear and re-link:

bootspring switch context clear bootspring auth login

Context Generation Issues#

"CLAUDE.md not generating"#

The context file fails to generate.

Solutions:

  1. Check write permissions:
touch CLAUDE.md
  1. Force regeneration:
bootspring generate --force
  1. Check for errors:
bootspring generate --verbose
  1. Verify project structure:
    • Must have package.json or recognizable project files

"Context missing my tech stack"#

Generated context doesn't include your framework.

Solutions:

  1. Specify stack explicitly:
1// bootspring.config.js 2module.exports = { 3 stack: { 4 frontend: ['react', 'nextjs', 'tailwindcss'], 5 backend: ['nodejs', 'express'], 6 database: ['postgresql', 'prisma'], 7 }, 8};
  1. Regenerate context:
bootspring generate --force

"Context is too large"#

CLAUDE.md is too big, causing issues.

Solutions:

  1. Exclude unnecessary files:
1// bootspring.config.js 2module.exports = { 3 context: { 4 exclude: [ 5 'node_modules/**', 6 '.git/**', 7 'dist/**', 8 'build/**', 9 'coverage/**', 10 '*.log', 11 ], 12 }, 13};
  1. Limit included sections:
bootspring generate --sections stack,commands,guidelines

Agent Issues#

"Agent not found"#

The specified agent doesn't exist.

Solutions:

  1. Check agent name:
bootspring agent list | grep frontend

  1. Use exact name:

    • Correct: frontend-expert
    • Wrong: frontend, FrontendExpert

  2. Check your tier:

    • Some agents require Pro or Team tier
bootspring agent list --show-tier

"Agent response seems generic"#

Agent isn't using project context.

Solutions:

  1. Regenerate context:
bootspring generate --force
  1. Verify CLAUDE.md exists and has content:
cat CLAUDE.md | head -50
  1. Be more specific in your request:

Instead of:

Use the frontend-expert to help with the form.

Try:

Use the frontend-expert to create a multi-step form with React Hook Form, Zod validation, and Tailwind CSS styling, following our existing component patterns.

"Pro agent not available"#

Trying to use an agent outside your tier.

Solution:

  1. Check which agents are available:
bootspring agent list
  1. Upgrade to Pro for business agents:
    • Visit bootspring.com/pro

Quality Gate Issues#

"Quality gate failing"#

Pre-commit or pre-push checks fail.

Solutions:

  1. See detailed errors:
bootspring quality pre-commit --verbose
  1. Fix issues automatically (if possible):
bootspring quality pre-commit --fix
  1. Skip specific checks temporarily:
1// bootspring.config.js 2module.exports = { 3 quality: { 4 'pre-commit': { 5 skip: ['format'], // Skip formatting check 6 }, 7 }, 8};

"TypeScript errors blocking commit"#

TypeScript errors prevent quality gate from passing.

Solutions:

  1. Run TypeScript check manually:
npx tsc --noEmit

  1. Fix the errors or adjust tsconfig:

    • Common issue: missing types for dependencies

  2. Install missing type packages:

npm install -D @types/node @types/react

"ESLint errors"#

Linting fails during quality checks.

Solutions:

  1. Run ESLint manually:
npx eslint . --ext .ts,.tsx
  1. Auto-fix issues:
npx eslint . --ext .ts,.tsx --fix
  1. Check ESLint config exists:
ls -la .eslintrc* eslint.config.*

Workflow Issues#

"Workflow stuck"#

A workflow isn't progressing.

Solutions:

  1. Check workflow status:
bootspring workflow status
  1. View workflow logs:
bootspring workflow logs <workflow-id>
  1. Resume if paused:
bootspring workflow resume <workflow-id>
  1. Restart if needed:
bootspring workflow restart <workflow-id>

"Workflow phase failed"#

A specific phase in the workflow failed.

Solutions:

  1. Retry the failed phase:
bootspring workflow retry <workflow-id> --phase <phase-name>
  1. Skip the phase (if non-critical):
bootspring workflow skip <workflow-id> --phase <phase-name>
  1. View phase details:
bootspring workflow logs <workflow-id> --phase <phase-name>

Performance Issues#

"Bootspring is slow"#

Commands take too long to execute.

Solutions:

  1. Check network connectivity:
ping api.bootspring.com
  1. Increase timeout:
1// bootspring.config.js 2module.exports = { 3 server: { 4 timeout: 60000, 5 }, 6};
  1. Use local caching:
1// bootspring.config.js 2module.exports = { 3 cache: { 4 enabled: true, 5 ttl: 3600, // 1 hour 6 }, 7};
  1. Check for large CLAUDE.md:
    • If over 100KB, add exclusions

"High memory usage"#

Bootspring uses too much memory.

Solutions:

  1. Restart the MCP server:

    • Restart your AI assistant

  2. Reduce context size:

    • Add exclusions to config

  3. Limit concurrent operations:

1// bootspring.config.js 2module.exports = { 3 server: { 4 maxConcurrent: 3, 5 }, 6};

Getting More Help#

Run Diagnostics#

bootspring doctor --full

Provides comprehensive system check with actionable advice.

Enable Debug Mode#

BOOTSPRING_DEBUG=true bootspring <command>

Shows detailed logs for debugging.

Check System Status#

Visit status.bootspring.com for:

  • Service status
  • Known issues
  • Maintenance windows

Contact Support#

  1. Dashboard: bootspring.com/dashboard/support
  2. Discord: Join the community server
  3. GitHub: File issues at github.com/bootspring/bootspring

Information to Include#

When reporting issues, include:

1# System info 2bootspring doctor --full 3 4# Version info 5bootspring --version 6node --version 7npm --version 8 9# Configuration 10cat bootspring.config.js 11cat .mcp.json

Common Error Messages#

ErrorMeaningSolution
ENOENT: no such fileFile not foundCheck path exists
EACCES: permission deniedNo permissionCheck file permissions
ETIMEDOUTRequest timeoutCheck network, increase timeout
ECONNREFUSEDServer not runningStart MCP server
Invalid tokenAuth failedRe-authenticate
Rate limit exceededToo many requestsWait and retry
Tier required: proFeature needs upgradeUpgrade plan

Next Steps#