Troubleshooting

Solutions to common issues when using Stellarion.

Installation Issues

"command not found: stellarion"

Stellarion is not in your PATH.

Solution:

npm list -g stellarion

npm install -g stellarion

npm config get prefix

Node.js Version Error

Stellarion requires Node.js 22 or higher.

Solution:

node --version

nvm install 22
nvm use 22

Permission Denied

Cannot install globally due to permissions.

Solution:

sudo npm install -g stellarion

Connection Issues

Tools Not Available in Claude Code

Claude Code can't see Stellarion tools.

Solutions:

1. Re-initialize:

   stellarion init
   

2. Restart Claude Code
3. Check configuration:

   stellarion status
   

MCP Connection Failed

Stellarion server not responding.

Solutions:

1. Check if another instance is running
2. Verify port availability
3. Check logs:

   STELLARION_LOG_LEVEL=debug stellarion status
   

Analysis Issues

Semantic Search Not Working

Search returns no or poor results.

Solutions:

1. Index your project:

   Index this project for semantic search
   

2. Check if project is indexed:

   stellarion status
   

3. Re-index with force:

   Re-index this project from scratch
   

Analysis is Slow

Operations take too long.

Solutions:

1. Limit file count for large projects
2. Analyze specific directories instead of entire project
3. Use pattern filters to narrow scope
4. Check available memory

Out of Memory

Process crashes or freezes.

Solutions:

1. Limit max files:

   Index with maximum 500 files
   

2. Analyze smaller directories
3. Close other applications
4. Increase Node.js memory:

   NODE_OPTIONS=--max-old-space-size=4096 stellarion init
   

File Issues

Files Not Found

Stellarion can't find expected files.

Solutions:

1. Check file paths are correct
2. Verify files aren't in .gitignore
3. Check file permissions
4. Use absolute paths

Wrong Files Analyzed

Analysis includes unwanted files.

Solutions:

1. Check .gitignore is properly configured
2. Use path filters in your queries
3. Exclude patterns:

   Analyze src/ excluding tests
   

Report Issues

Report Generation Fails

Cannot create reports.

Solutions:

1. Ensure write permissions to output directory
2. Check disk space
3. Specify a different output path
4. Use a different format (json instead of html)

Incomplete Reports

Reports missing expected data.

Solutions:

1. Index project first
2. Check analysis completed without errors
3. Increase analysis scope
4. Check file type support

Model Issues

RoBERTa Model Not Found

Semantic search fails due to missing models.

Solution:

curl -sSL https://stellarion.dev/download-models.sh | bash

ROBERTA_MODEL_PATH=/path/to/models/roberta-base

Model Loading Failed

Model files corrupted or incompatible.

Solution:

rm -rf ~/.stellarion/models
curl -sSL https://stellarion.dev/download-models.sh | bash

Getting Help

If you can't resolve an issue:

1. Check logs with debug level:

   STELLARION_LOG_LEVEL=debug stellarion status
   

2. Include in bug reports:
   • Stellarion version
   • Node.js version
   • Operating system
   • Error messages
   • Steps to reproduce