Troubleshooting

Common Issues

Authentication Errors

"Access key not found"

⛓️‍💥 Symptom:

Access key not found.
ℹ️ To configure your access key, set CONSTELLATION_ACCESS_KEY environment
   variable to the value of your access key or run 'constellation auth'.

🪛 Solution:

# Option 1: Interactive setup
constellation auth

# Option 2: Manual environment variable
export CONSTELLATION_ACCESS_KEY=your-access-key

# Verify it's set
echo $CONSTELLATION_ACCESS_KEY

"Authentication failed" (401 Unauthorized)

🔍 Cause:

Invalid, inactive, or expired access key
Incorrect environment variable value

🪛 Solution:

Verify your access key is correct:
```
echo $CONSTELLATION_ACCESS_KEY
```
Re-configure authentication:
```
constellation auth
```
Ensure your access key hasn't expired and is still active

Configuration Errors

"Unable to find constellation config"

⛓️‍💥 Symptom:

❌ Unable to find constellation config at constellation.json

🪛 Solution:

# Initialize the project
constellation init

"constellation.json already exists"

⛓️‍💥 Symptom:

✅ Found existing constellation.json file, project already initialized.

This is informational - Your project is already initialized. No action needed.

"Invalid configuration: [field] is missing"

Common missing fields:

branch
languages
projectId

🪛 Solution:

Option 1 - Regenerate configuration:

# Backup existing config
mv constellation.json constellation.json.backup

# Reinitialize
constellation init

Option 2 - Manually edit constellation.json:

{
  "projectId": "proj:00000000000000000000000000000000",
  "branch": "main",
  "languages": {
    "typescript": {
      "fileExtensions": [".ts", ".tsx"]
    },
    "javascript": {
      "fileExtensions": [".js", ".jsx"]
    }
  },
  "exclude": ["node_modules/**", "dist/**", "*.test.ts"]
}

"Invalid configuration: file extension must start with a dot"

🪛 Solution:

Edit constellation.json to ensure all file extensions start with .:

{
  "languages": {
    "typescript": {
      "fileExtensions": [".ts", ".tsx"] // ✅ Correct
    },
    "python": {
      "fileExtensions": ["py"] // ❌ Wrong - missing dot
    }
  }
}

Git & Version Control Errors

"Could not find git client installation"

⛓️‍💥 Symptom:

⚠️ Could not find git client installation.
ℹ️ Constellation requires git, please install git and try again.

🪛 Solution:

Install Git from https://git-scm.com/downloads
Verify installation:
```
git --version
```
Retry the command

"Current directory is not a git repository"

⛓️‍💥 Symptom:

⚠️ Current directory is not a git repository.
ℹ️ Please run this command from the root directory of a git repository.

🪛 Solution:

# Initialize git repository
git init

# Create initial commit
git add .
git commit -m "Initial commit"

# Then run constellation command
constellation init

"Branch not configured for indexing" / Branch Mismatch

⛓️‍💥 Symptom:

Current branch "feature-x" does not match configured branch "main".
Update constellation.json or switch to "main" branch.

🪛 Solution:

Option 1 - Switch to configured branch:

git checkout main
constellation index

Option 2 - Update configuration to match current branch:

# Edit constellation.json and change "branch" field
# Or reinitialize
constellation init

"Not on a Git branch (detached HEAD state)"

🪛 Solution:

# Checkout the branch you want to index
git checkout main

# Verify
git branch --show-current

constellation index

"No commits found in repository"

🪛 Solution:

# Create an initial commit
git add .
git commit -m "Initial commit"

constellation index

"Outstanding changes detected"

⛓️‍💥 Symptom:

Outstanding changes detected.
Commit or stash changes first to ensure consistent indexing.

🪛 Solution:

Option 1 - Commit your changes:

git add .
git commit -m "Your commit message"
constellation index

Option 2 - Stash temporarily:

git stash
constellation index
git stash pop

Option 3 - Skip validation (not recommended):

constellation index --dirty

"Remote origin URL not found"

🪛 Solution:

# Add remote origin
git remote add origin https://github.com/username/repo.git

# Or update existing remote
git remote set-url origin https://github.com/username/repo.git

# Verify
git remote -v

"Pull failed: Authentication error"

⛓️‍💥 Symptom:

❌ Pull failed: Authentication error - check your credentials

🪛 Solution:

# Verify your git credentials
git config user.name
git config user.email

# For SSH
ssh -T git@github.com

# For HTTPS, configure credential helper
git config --global credential.helper store  # Linux
# or
git config --global credential.helper osxkeychain  # macOS
# or
git config --global credential.helper wincred  # Windows

"Pull failed: Network error"

⛓️‍💥 Symptom:

❌ Pull failed: Network error - unable to reach remote repository

🪛 Solution:

# Check network connectivity
ping github.com  # Or your git provider

# Check if you can access the repository
git ls-remote origin

# If network is working, try manual pull
git pull

# If still failing, skip synchronization
constellation index --dirty

"Pull failed due to merge conflicts"

⛓️‍💥 Symptom:

❌ Pull failed due to merge conflicts
   Run "git status" to see conflicted files

🪛 Solution:

# 1. Check conflicted files
git status

# 2. Resolve conflicts in each file manually
# (Open files and fix conflicts)

# 3. Stage resolved files
git add <resolved-files>

# 4. Complete the merge
git commit

# 5. Retry indexing
constellation index

"Cannot pull: Working directory has uncommitted changes"

See "Outstanding changes detected" above.

File System Errors

"Skipping symlink pointing outside project"

⛓️‍💥 Symptom:

⚠️ Skipping symlink pointing outside project: /path/to/link -> /outside/project

🔍 Cause: Security feature prevents indexing files outside the project directory

🪛 Solution:

If the symlink target is needed, move it inside the project
Or remove the symlink if not needed

"Skipping invalid symlink"

⛓️‍💥 Symptom:

⚠️ Skipping invalid symlink: /path/to/broken-link

🔍 Cause: Broken symlink (target doesn't exist)

🪛 Solution:

# Check the symlink
ls -la /path/to/broken-link

# Fix the target or remove the broken symlink
rm /path/to/broken-link

"Skipping inaccessible file"

⛓️‍💥 Symptom:

⚠️ Skipping inaccessible file: /path/to/file

🔍 Cause:

No read permission on file
File was deleted after detection

🪛 Solution:

# Check file permissions
ls -la /path/to/file

# Fix permissions
chmod +r /path/to/file

# Or run full index to rescan
constellation index --full

"Error walking directory"

⛓️‍💥 Symptom:

❌ Error walking directory /path/to/dir: Permission denied

🪛 Solution:

# Check directory permissions
ls -ld /path/to/dir

# Fix permissions
chmod +rx /path/to/dir

"Failed to load .gitignore"

⛓️‍💥 Symptom:

⚠️ Failed to load .gitignore: /path/to/.gitignore

Impact: Non-blocking - indexing continues, but that specific .gitignore is skipped

🪛 Solution:

# Check .gitignore permissions
ls -la /path/to/.gitignore

# Fix permissions
chmod +r /path/to/.gitignore

Parsing & Language Errors

"Unsupported language"

⛓️‍💥 Symptom:

Unsupported language: rust

Supported languages:

bash, c, c-sharp, cpp, go, java, javascript, json, php, python, ruby, typescript

🪛 Solution:

Remove unsupported languages from constellation.json:

{
  "languages": {
    "typescript": { "fileExtensions": [".ts", ".tsx"] },
    "javascript": { "fileExtensions": [".js", ".jsx"] }
  }
}

"Failed to load language"

⛓️‍💥 Symptom:

Failed to load language: typescript

🔍 Cause: Tree-sitter parser module missing or corrupted

🪛 Solution:

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# If still failing, rebuild native modules
npm rebuild

"Failed to parse [file]"

⛓️‍💥 Symptom:

⚠️ Failed to parse src/app.ts: Unexpected token

Impact: Non-blocking - the file is skipped, indexing continues with other files

🔍 Cause:

Syntax errors in source code
Malformed file encoding
Unsupported language constructs

🪛 Solution:

Fix syntax errors in the reported file
Ensure file is properly UTF-8 encoded
Retry indexing

Network & Service Errors

Note: You do not run or manage the Constellation API service. These errors indicate service availability issues. Contact support if errors persist.

"Connection refused - service may be down"

⛓️‍💥 Symptom:

Failed to upload data to Constellation Service: Connection refused

What this means: The Constellation service is temporarily unavailable or experiencing issues.

What you can do:

Wait a few minutes and retry - the issue may be temporary

Check your network connectivity:

# Verify you have internet access
ping 8.8.8.8

Contact support if the issue persists

"DNS lookup failed"

⛓️‍💥 Symptom:

Failed to upload data to Constellation Service: DNS lookup failed

What this means: Unable to resolve the Constellation service hostname.

What you can do:

Check your DNS/network connectivity:

# Try accessing a known website
ping google.com

If using a VPN, try disconnecting and reconnecting
Contact support if DNS resolution works for other sites but not Constellation

"Connection timeout - service not responding"

⛓️‍💥 Symptom:

Failed to upload data to Constellation Service: Connection timeout

What this means: The service is not responding within the timeout period.

What you can do:

Check your network connectivity:
```
# Test general connectivity
ping 8.8.8.8
```
Check firewall/proxy settings - ensure outbound connections are allowed
Retry - the CLI automatically retries transient errors
Contact support if timeouts persist

"Connection reset by server"

⛓️‍💥 Symptom:

Failed to upload data to Constellation Service: Connection reset by server

What this means: The connection was interrupted during data transfer.

What you can do:

Retry indexing - the CLI will automatically retry up to 3 times
Check your network stability - ensure you have a stable internet connection
Contact support if the issue persists

"Host unreachable"

⛓️‍💥 Symptom:

Failed to upload data to Constellation Service: Host unreachable

What this means: Your system cannot route network traffic to the Constellation service.

What you can do:

Check general network connectivity:
```
ping 8.8.8.8
```
If using a VPN, ensure it's connected and configured properly
Check firewall rules - ensure outbound HTTPS connections are allowed
Contact support if network connectivity is working for other services

HTTP 5xx Errors (500, 502, 503, 504)

⛓️‍💥 Symptom:

HTTP request attempt 1/3 failed: Service Unavailable (503)

What this means: The Constellation service is experiencing internal errors or high load.

Automatic behavior: The CLI retries up to 3 times with exponential backoff.

What you can do:

Wait for automatic retries to complete
If all retries fail, wait a few minutes and try again
Contact support if errors persist

Environment Variable Errors

"Environment variable name must contain only letters, numbers, and underscores"

🪛 Solution:

# Use valid variable name
constellation auth  # Interactive prompt validates names

# Or set manually with valid name
export CONSTELLATION_ACCESS_KEY=your-key

"Failed to set environment variable"

On Windows:

Run terminal/PowerShell as Administrator
Retry constellation auth

On macOS/Linux:

# Check shell config file permissions
ls -la ~/.zshrc  # or ~/.bashrc

# Fix permissions if needed
chmod 644 ~/.zshrc

# Or set manually
echo 'export CONSTELLATION_ACCESS_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

Build Configuration Errors

"Failed to parse config for tsconfig.json/jsconfig.json"

⛓️‍💥 Symptom:

⚠️ Failed to parse config for tsconfig.json: Unexpected token

Impact: Non-blocking - import path resolution may not work for that file

🪛 Solution:

# Validate JSON syntax
node -e "console.log(JSON.parse(require('fs').readFileSync('tsconfig.json', 'utf8')))"

# Fix syntax errors in tsconfig.json or jsconfig.json

Initialization Workflow

Follow this sequence for first-time setup:

# 1. Ensure you're in a Git repository
git init
git add .
git commit -m "Initial commit"

# 2. Initialize Constellation configuration
constellation init

# 3. Configure authentication
constellation auth
# Enter your access key when prompted

# 4. Verify configuration
cat constellation.json
echo $CONSTELLATION_ACCESS_KEY

# 5. Run first index
constellation index

Best Practices

Before Each Index

Commit your changes:

git status  # Should show clean working tree
git add .
git commit -m "Your message"

Ensure you're on the correct branch:

git branch --show-current
# Should match "branch" in constellation.json

Verify authentication:

echo $CONSTELLATION_ACCESS_KEY
# Should display your access key

Configuration Checklist

Your constellation.json should look like:

{
  "projectId": "proj:00000000000000000000000000000000",
  "branch": "main",
  "languages": {
    "typescript": {
      "fileExtensions": [".ts", ".tsx"]
    },
    "javascript": {
      "fileExtensions": [".js", ".jsx"]
    }
  },
  "exclude": [
    "node_modules/**",
    "dist/**",
    "build/**",
    "*.test.ts",
    "*.spec.ts"
  ]
}

Required fields:

✅ projectId - Project identifier (from your Constellation web dashboard)
✅ branch - Git branch to index (must match current branch)
✅ languages - At least one language with file extensions starting with .

Optional fields:

exclude - Glob patterns for files/directories to skip
Custom language configurations

Getting Help

If you encounter an issue not covered here:

Check the error message - most errors include recovery suggestions
Verify configuration - run through the Configuration Checklist
Review logs - errors often include detailed context
Try a full index - constellation index --full rescans everything
Contact support - provide the full error message and context

Useful Debug Commands

# Show current configuration
cat constellation.json

# Show authentication status
echo $CONSTELLATION_ACCESS_KEY

# Check git status
git status
git branch --show-current
git remote -v

# Check network connectivity
ping 8.8.8.8

# Run full index (rescans all files)
constellation index --full

Common Issues​

Authentication Errors​

"Access key not found"​

"Authentication failed" (401 Unauthorized)​

Configuration Errors​

"Unable to find constellation config"​

"constellation.json already exists"​

"Invalid configuration: [field] is missing"​

"Invalid configuration: file extension must start with a dot"​

Git & Version Control Errors​

"Could not find git client installation"​

"Current directory is not a git repository"​

"Branch not configured for indexing" / Branch Mismatch​

"Not on a Git branch (detached HEAD state)"​

"No commits found in repository"​

"Outstanding changes detected"​

"Remote origin URL not found"​

"Pull failed: Authentication error"​

"Pull failed: Network error"​

"Pull failed due to merge conflicts"​

"Cannot pull: Working directory has uncommitted changes"​

File System Errors​

"Skipping symlink pointing outside project"​

"Skipping invalid symlink"​

"Skipping inaccessible file"​

"Error walking directory"​

"Failed to load .gitignore"​

Parsing & Language Errors​

"Unsupported language"​

"Failed to load language"​

"Failed to parse [file]"​

Network & Service Errors​

"Connection refused - service may be down"​

"DNS lookup failed"​

"Connection timeout - service not responding"​

"Connection reset by server"​

"Host unreachable"​

HTTP 5xx Errors (500, 502, 503, 504)​

Environment Variable Errors​

"Environment variable name must contain only letters, numbers, and underscores"​

"Failed to set environment variable"​

Build Configuration Errors​

"Failed to parse config for tsconfig.json/jsconfig.json"​

Initialization Workflow​

Best Practices​

Before Each Index​

Configuration Checklist​

Getting Help​

Useful Debug Commands​

Common Issues

Authentication Errors

"Access key not found"

"Authentication failed" (401 Unauthorized)

Configuration Errors

"Unable to find constellation config"

"constellation.json already exists"

"Invalid configuration: [field] is missing"

"Invalid configuration: file extension must start with a dot"

Git & Version Control Errors

"Could not find git client installation"

"Current directory is not a git repository"

"Branch not configured for indexing" / Branch Mismatch

"Not on a Git branch (detached HEAD state)"

"No commits found in repository"

"Outstanding changes detected"

"Remote origin URL not found"

"Pull failed: Authentication error"

"Pull failed: Network error"

"Pull failed due to merge conflicts"

"Cannot pull: Working directory has uncommitted changes"

File System Errors

"Skipping symlink pointing outside project"

"Skipping invalid symlink"

"Skipping inaccessible file"

"Error walking directory"

"Failed to load .gitignore"

Parsing & Language Errors

"Unsupported language"

"Failed to load language"

"Failed to parse [file]"

Network & Service Errors

"Connection refused - service may be down"

"DNS lookup failed"

"Connection timeout - service not responding"

"Connection reset by server"

"Host unreachable"

HTTP 5xx Errors (500, 502, 503, 504)

Environment Variable Errors

"Environment variable name must contain only letters, numbers, and underscores"

"Failed to set environment variable"

Build Configuration Errors

"Failed to parse config for tsconfig.json/jsconfig.json"

Initialization Workflow

Best Practices

Before Each Index

Configuration Checklist

Getting Help

Useful Debug Commands