Skip to main content

Troubleshooting

Common issues and solutions for the Constellation MCP Server when used with coding assistants like Claude Code, GitHub Copilot, and other MCP-compatible development tools.

Setup and Configuration Issues​

Configuration Not Found​

⛓️‍💥 Symptom:

Configuration Error - Constellation MCP Server

I cannot execute this tool because constellation.json is not found in your git repository.

🔍 Cause:

The Constellation MCP server requires a constellation.json configuration file at the root of your git repository.

🪛 Solution:

  1. Navigate to your git repository root directory

  2. Initialize Constellation:

    constellation init

Note: The server will start in "degraded mode" without a config file, but tools will return setup instructions instead of results.

Invalid Configuration Errors​

⛓️‍💥 Symptom:

Invalid configuration: branch is missing
Invalid configuration: no languages configured
Invalid configuration: projectId is missing

🔍 Cause:

Your constellation.json file is missing required fields or contains invalid values.

🪛 Solution:

  1. Check Required Fields:

    {
      "branch": "main",
      "projectId": "proj:00000000000000000000000000000000",
      "languages": {
        "typescript": {
          "fileExtensions": [".ts", ".tsx"]
        }
      }
    }

  2. Validate Language Configuration: Each language must have at least one file extension:

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

  3. Validate File Extensions: All file extensions must start with a dot:

    • .ts, .tsx, .js (correct)
    • ts, tsx, js (incorrect)

  4. Recreate Configuration:

    rm constellation.json
    constellation init

Authentication Errors​

Authentication Failed​

⛓️‍💥 Symptom:

Authentication Failed

The Constellation API rejected your access key.

🔍 Cause:

  • Missing CONSTELLATION_ACCESS_KEY environment variable
  • Invalid API key
  • Expired API key

🪛 Solution:

  1. Set up authentication via CLI:

    constellation auth

  2. Verify environment variable:

    echo $CONSTELLATION_ACCESS_KEY

    Should output your Access Key (not empty).

  3. Restart your coding assistant after updating authentication.

Verification:

Check the MCP server logs on startup for:

[CONSTELLATION] Environment check:
  CONSTELLATION_ACCESS_KEY: ***SET***

If you see NOT SET, run constellation auth again.

Project Not Indexed​

Project Not Found in Index​

⛓️‍💥 Symptom:

Project Not Indexed

The project cannot be found in the Constellation index.

Project Details:
  Project ID: proj:00000000000000000000000000000000
  Branch: main

🔍 Cause:

  • The project hasn't been indexed yet
  • You're on a different branch than what was indexed
  • The project ID in constellation.json doesn't match the indexed project

🪛 Solution:

  1. Index your codebase:

    constellation index

  2. Verify you're on the correct branch:

    git branch --show-current

    The branch should match the branch field in your constellation.json.

  3. Use full re-index if incremental fails:

    constellation index --full

  4. Switch branches if needed (each branch has a separate index):

    git checkout feature-branch
    constellation index

No Data Found / Empty Results​

⛓️‍💥 Symptom:

No data found. This may indicate:
1. The project hasn't been indexed yet
2. The specified item doesn't exist
3. Project needs re-indexing

🔍 Cause:

  • Project not indexed
  • Search query too restrictive
  • Symbol/file doesn't exist in the indexed data
  • Stale index after code changes

🪛 Solution:

  1. Re-index the project:

    constellation index

  2. Use full re-index:

    constellation index --full

  3. Broaden search criteria in your code:

    // Too restrictive
    const result = await api.searchSymbols({
      query: 'handleUserAuthenticationRequest',
      filterByKind: ['function'],
      isExported: true
    });

    // Broader search
    const result = await api.searchSymbols({
      query: 'handleUser',
      limit: 20
    });

Symbol and File Issues​

Symbol Not Found​

⛓️‍💥 Symptom:

Symbol not found: MyClass

🔍 Cause:

  • Symbol doesn't exist
  • Incorrect symbol identifier format
  • Symbol not indexed (private/local symbols may not be indexed)

🪛 Solution:

  1. Correct AI assistant: Tell your AI assistant to reconsider the symbol for which it is searching and, if possible, provide it with the valid symbol name.

  2. Update the project index:

    constellation index

File Not Found​

⛓️‍💥 Symptom:

File not found: src/components/Button.tsx

🔍 Cause:

  • File doesn't exist
  • Incorrect file path (relative vs absolute)
  • File not tracked by git
  • File not in configured languages

🪛 Solution:

  1. Check if file is tracked:

    git ls-files | grep Button.tsx

    Untracked files are not indexed.

  2. Check language configuration in constellation.json:

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

  3. Use relative paths from project root:

    • src/components/Button.tsx (correct)
    • /Users/name/project/src/components/Button.tsx (incorrect)

  4. Update the project index after adding files:

    constellation index

MCP Server Issues​

Server Failed to Start​

⛓️‍💥 Symptom:

CONSTELLATION MCP SERVER FAILED TO START

🔍 Cause:

  • Configuration errors
  • Missing dependencies
  • Incompatible Node.js version
  • Permission issues

🪛 Solution:

  1. Check the specific error message displayed above the failure banner.

  2. Verify installation:

    npm install -g @constellationdev/mcp
    # or
    npx -y @constellationdev/mcp

  3. Check Node.js version:

    node --version  # Should be v18.0.0 or higher

  4. Check your coding assistant's logs for detailed error messages.

Degraded Mode Warning​

⛓️‍💥 Symptom:

[CONSTELLATION] WARNING: Server starting in degraded mode
[CONSTELLATION] Configuration error: ...
[CONSTELLATION] Tools will return setup instructions when called

🔍 Cause:

  • Missing or invalid constellation.json
  • Configuration loading error

Behavior:

  • Server starts successfully
  • The execute_code tool returns setup instructions instead of executing code
  • Allows your coding assistant to guide you through setup

🪛 Solution:

Follow the setup instructions in the configuration error message:

  1. Run constellation init
  2. Run constellation auth
  3. Run constellation index
  4. Restart your coding assistant or reload the MCP server

Getting Help​

If you continue to experience issues:

  1. Check Documentation:

  2. Collect Debug Information:

    # Check configuration
    cat constellation.json

    # Check authentication
    echo $CONSTELLATION_ACCESS_KEY

    # Re-index fully
    constellation index --full

  3. Check your coding assistant's logs:

    • Claude Desktop: Check the OUTPUT panel
    • VS Code extensions: Check the extension output
    • Other assistants: Refer to their documentation

  4. Report Issues: