Skip to main content

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 'const auth'.

🪛 Solution:

# Option 1: Interactive setup
const 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:

  1. Verify your access key is correct:

    echo $CONSTELLATION_ACCESS_KEY

  2. Re-configure authentication:

    npx @constellationdev/cli auth

  3. Ensure your access key hasn't expired and is still active

Configuration Errors​

"Unable to find const config"​

⛓️‍💥 Symptom:

❌ Unable to find const config at constellation.json

🪛 Solution:

# Initialize the project
const 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:

  1. Option 1 - Regenerate configuration:

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

    # Reinitialize
    const init

  2. 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:

  1. Install Git from https://git-scm.com/downloads

  2. Verify installation:

    git --version

  3. 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 const command
const 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
const index

Option 2 - Update configuration to match current branch:

# Edit constellation.json and change "branch" field
# Or reinitialize
const 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

const index

"No commits found in repository"​

🪛 Solution:

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

const 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"
const index

Option 2 - Stash temporarily:

git stash
const index
git stash pop

Option 3 - Skip validation (not recommended):

const 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
const 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
const index

"Cannot pull: Working directory has uncommitted changes"​

See "Outstanding changes detected" above.

File System Errors​

⛓️‍💥 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

⛓️‍💥 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
const 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:

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

Index Enrichment Issues​

"No language servers started, index enrichment skipped"​

This is informational — enrichment is optional. The core index completed successfully.

🔍 Cause: No compatible language servers were found on your system for the indexed languages.

🪛 Solution (optional — enrichment enhances but is not required for indexing):

  1. Install the language server for your project's language:

    # TypeScript / JavaScript
    npm install -g typescript-language-server typescript

    # Python
    pip install pyright

    # Go (requires the Go toolchain — https://go.dev/dl/)
    go install golang.org/x/tools/gopls@latest
    # then ensure $GOPATH/bin (or ~/go/bin) is on your PATH

  2. Verify it's available in your PATH:

    which typescript-language-server  # or: which pyright-langserver, which gopls

  3. Re-run indexing — enrichment will be detected automatically.

Alternatively, the const init command can install language servers to ~/.constellation/lsp-servers/ for you during project setup — TypeScript / Python via npm install, and Go's gopls via go install (provided the Go toolchain is already on your PATH). If the toolchain isn't installed, init prints the install command instead so you can install it yourself.

"Index enrichment failed"​

🔍 Cause: A language server started but encountered an error during enrichment queries.

Impact: Non-blocking — the core index completed successfully. Enrichment data from this run is discarded.

🪛 Solution:

  1. Verify the language server works independently:

    # Check if the server starts without errors
    typescript-language-server --stdio
    # (Press Ctrl+C to exit)

  2. Ensure your project has valid configuration files (tsconfig.json, pyrightconfig.json, etc.)

  3. Try re-running the index — the issue may be transient

  4. If the problem persists, you can skip enrichment:

    const index --no-enrich

Disabling Enrichment​

If enrichment causes issues or you want to skip it:

Per run:

const index --no-enrich

Per language (in constellation.json):

{
  "languages": {
    "python": {
      "fileExtensions": [".py"],
      "lspEnrichment": false
    }
  }
}

Globally (in constellation.json):

{
  "lspEnrichment": false
}

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:

  1. Wait a few minutes and retry - the issue may be temporary
  2. Check your network connectivity: 
    # Verify you have internet access
    ping 8.8.8.8
  3. 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:

  1. Check your DNS/network connectivity: 
    # Try accessing a known website
    ping google.com
  2. If using a VPN, try disconnecting and reconnecting
  3. 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:

  1. Check your network connectivity: 
    # Test general connectivity
    ping 8.8.8.8
  2. Check firewall/proxy settings - ensure outbound connections are allowed
  3. Retry - the CLI automatically retries transient errors
  4. 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:

  1. Check general network connectivity: 
    ping 8.8.8.8
  2. If using a VPN, ensure it's connected and configured properly
  3. Check firewall rules - ensure outbound HTTPS connections are allowed
  4. 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
const 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 const 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
const init

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

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

# 5. Run first index
const index

Best Practices​

Before Each Index​

  1. Commit your changes:

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

  2. Ensure you're on the correct branch:

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

  3. 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:

  1. Check the error message - most errors include recovery suggestions
  2. Verify configuration - run through the Configuration Checklist
  3. Review logs - errors often include detailed context
  4. Try a full index - const index --full rescans everything
  5. 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)
const index --full