agentsclimarketplace
Sign in

Constellation troubleshooting

Skill ShiftinBits/constellation-claude/skills/constellation-troubleshooting

This skill should be used when the user asks about "Constellation errors", "fix Constellation", "debug Constellation", "Constellation not working", "API connection issues", "indexing problems", "MCP server", "Failed to reconnect", mentions any Constellation error codes (AUTH_ERROR, PROJECT_NOT_INDEXED, etc.), or when Constellation commands fail.From its SKILL.md

Install
npx -y skills add ShiftinBits/constellation-claude --skill constellation-troubleshooting

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

4 things to look at

  • reads credentialsReads from 1 credential source: `CONSTELLATION_ACCESS_KEY`.
  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
  • runs commandsInstructs the agent to run 4 commands, including `npx @constellationdev/cli auth` and 3 more.
  • fetches URLsInstructs the agent to fetch 1 URL, including https://status.constellationdev.io/.

SKILL.md

3.3 KB, 684 tokens by cl100k_base, as published. Nobody here has run it

Constellation Troubleshooting

Quick diagnostic procedures for Constellation plugin issues.

Quick Diagnosis Flowchart

Issue Reported
     |
     v
Can mcp__constellation__code_intel be called?
     |                    |
    YES                   NO
     |                    |
     v                    v
  API Error          MCP Server Issue
 (has code)         (see MCP Diagnosis)
     |
     v
Check error.code:
- AUTH_ERROR --> Authentication section
- PROJECT_NOT_INDEXED --> Indexing section
- SYMBOL_NOT_FOUND --> Query Issues section
- API_UNREACHABLE --> Connectivity section

MCP Server Issues

Symptom: "Failed to reconnect to plugin:constellation:constellation" or tool calls fail entirely.

Cause: The MCP server isn't starting or is crashing.

Quick Fixes:

  1. Restart Claude Code - MCP connections initialize at startup

  2. Verify MCP configuration:

    Note, the tool is built into the constellation plugin, but should accurately reflect the following:

    {
  "mcpServers": {
    "constellation": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@constellationdev/mcp@latest"],
      "env": {
        "CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}"
      }
    }
  }
}

Authentication Issues (AUTH_ERROR)

Symptom: "Authentication failed" or "Invalid API key"

Quick Fixes:

  1. Configure credentials:

    npx @constellationdev/cli auth

  2. Check if access key is properly set:

    In the event of AUTH_ERROR failures the MCP server provides details in the error.guidance[0] value of the response object, indicating the current state of the CONSTELLATION_ACCESS_KEY environment variable.

  3. If key is expired: Regenerate in Constellation web UI under Settings > API Keys

Indexing Issues (PROJECT_NOT_INDEXED)

Symptom: "Project not indexed" or empty results

Quick Fixes:

  1. Index the project:

    cd /path/to/your/project
constellation index --full

  2. Force reindex if stale:

    constellation index --full --force

Connectivity Issues (API_UNREACHABLE)

Symptom: Timeout or connection refused

Quick Fixes:

  1. Check network connectivity

  2. Check Constellation status at https://status.constellationdev.io/

Query Issues (SYMBOL_NOT_FOUND, FILE_NOT_FOUND)

These are typically not errors - the item simply wasn't found in the index.

Troubleshooting:

  1. Try partial/broader search terms
  2. Check spelling and case sensitivity
  3. Verify the file extension is in configured languages
  4. Re-index if the file was recently added

Diagnostic Command

Run /constellation:diagnose for a quick health check that tests:

  • MCP server connectivity
  • API authentication
  • Project indexing status

See references/error-codes.md for complete error code documentation.

What ships with it: 1 file

4.5 KB alongside SKILL.md

references/

Gives 0 of the 12 instructions most debug triage skills give in 684 tokens

Counted across 1,020 of the 1,639 authors here whose files we hold, read 2026-09-06

  • Find root cause before attempting any fixin 134 of 1020, across 118 files
  • Create a failing test case before implementing a fixin 109 of 1020, across 95 files
  • Read error messages and stack traces completelyin 102 of 1020, across 88 files
  • Reproduce the issue consistently before investigatingin 90 of 1020, across 77 files
  • Make the smallest possible change to test a hypothesisin 90 of 1020, across 76 files
  • Trace data flow backward to find the sourcein 84 of 1020, across 70 files
  • Form a single hypothesis before testingin 78 of 1020, across 64 files
  • Implement only one fix at a timein 76 of 1020, across 63 files
  • Question the architecture if three fixes failin 73 of 1020, across 59 files
  • Add diagnostic instrumentation at component boundariesin 68 of 1020, across 56 files
  • Compare broken code against working examplesin 68 of 1020, across 57 files
  • Write a regression test before applying the fixin 62 of 1020, across 55 files

Said here and by no other author read

  • Run authentication command for auth errors
  • Regenerate expired API keys in web UI
  • Run full index command for indexing errors
  • Force reindex if project data is stale
  • Check network connectivity for API unreachable errors
  • Verify status page for service outages

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.