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:

Alternative - use npx:

"Permission denied" during install#

npm doesn't have permission to install globally.

Solution (macOS/Linux):

"Node version not supported"#

Bootspring requires Node.js 18+.

Solution:

MCP Connection Issues#

"MCP server not connecting"#

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

Solutions:

1. Check .mcp.json exists:

1. Verify .mcp.json content:

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

2. Check if server starts manually:

1. Verify Node.js is accessible:

"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:

1. Check server logs:

"Connection timeout"#

MCP server times out during requests.

Solutions:

1. Increase timeout in config:

1. Check network connectivity:

1. Verify API key is valid:

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:

"Device limit reached"#

You've reached the maximum devices for your tier.

Solutions:

1. Check device count:

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:

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:

Or if you're already authenticated:

"Wrong project context"#

Commands are using a different project than expected.

Solutions:

1. Check current project:

1. Switch to 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:

Context Generation Issues#

"CLAUDE.md not generating"#

The context file fails to generate.

Solutions:

1. Check write permissions:

1. Force regeneration:

1. Check for errors:

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. Regenerate context:

"Context is too large"#

CLAUDE.md is too big, causing issues.

Solutions:

1. Exclude unnecessary files:

1. Limit included sections:

Agent Issues#

"Agent not found"#

The specified agent doesn't exist.

Solutions:

1. Check agent name:

1. Use exact name:

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

2. Check your tier:

   • Some agents require Pro or Team tier

"Agent response seems generic"#

Agent isn't using project context.

Solutions:

1. Regenerate context:

1. Verify CLAUDE.md exists and has content:

1. Be more specific in your request:

Instead of:

Try:

"Pro agent not available"#

Trying to use an agent outside your tier.

Solution:

1. Check which agents are available:

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:

1. Fix issues automatically (if possible):

1. Skip specific checks temporarily:

"TypeScript errors blocking commit"#

TypeScript errors prevent quality gate from passing.

Solutions:

1. Run TypeScript check manually:

1. Fix the errors or adjust tsconfig:

   • Common issue: missing types for dependencies

2. Install missing type packages:

"ESLint errors"#

Linting fails during quality checks.

Solutions:

1. Run ESLint manually:

1. Auto-fix issues:

1. Check ESLint config exists:

Workflow Issues#

"Workflow stuck"#

A workflow isn't progressing.

Solutions:

1. Check workflow status:

1. View workflow logs:

1. Resume if paused:

1. Restart if needed:

"Workflow phase failed"#

A specific phase in the workflow failed.

Solutions:

1. Retry the failed phase:

1. Skip the phase (if non-critical):

1. View phase details:

Performance Issues#

"Bootspring is slow"#

Commands take too long to execute.

Solutions:

1. Check network connectivity:

1. Increase timeout:

1. Use local caching:

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:

Getting More Help#

Run Diagnostics#

Provides comprehensive system check with actionable advice.

Enable Debug Mode#

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. Email: bugs@bootspring.com

Information to Include#

When reporting issues, include:

Common Error Messages#

Next Steps#

• Configuration - Customize Bootspring
• CLI Reference - All commands documented
• FAQ - Frequently asked questions