Endor Labs Scan Error Troubleshooter

Input Parsing

Accept input as: pasted error text, scan-and-diagnose request, or natural language description.

If no error text provided, ask:

1. Run a scan on the current repository and diagnose errors?
2. Analyze error text you paste in?

For scan mode, use scan MCP tool: path=repo path, scantypes=["vulnerabilities", "dependencies"], scanoptions={ "quick_scan": true }. Parse results for errors and match against knowledge base.

Workflow

Step 1: Detect Ecosystem

No match? Check cross-ecosystem patterns (GitHub Packages, registry/artifactory, sandbox errors).

Step 2: Classify Error Category

Auth Conflict -- persistent auth error loop, "multiple authentication", "conflicting auth", "invalid permissions" or repeated auth failures despite valid credentials. Root cause: both ~/.endorctl/config.yaml AND auth env vars (ENDORMCPSERVERAUTHMODE, ENDORNAMESPACE, ENDORAPI) in settings.json/mcp.json are present simultaneously.

Private Registry -- package not found, auth failures (401/403), SSH/Git credential errors, connection refused/timeout, missing registry config.

Toolchain -- language/SDK version mismatches, missing SDKs/build tools, lock file format issues, compiler/build config errors.

Other -- invalid manifests, compilation errors, missing build deps, plugin failures.

Step 3: Match Against Known Patterns

Read references/error-knowledge-base.md and match the error text against patterns for the detected ecosystem and category.

Step 4: Present Diagnosis

## Scan Error Diagnosis

### Error Identified

| Field | Value |
|-------|-------|
| Ecosystem | {ecosystem} |
| Category | {Private Registry / Toolchain / Other} |
| Error | {description} |
| Fixable | {Yes / No / Partially} |

### What This Means
{Plain-language explanation}

### Resolution
{Step-by-step remediation from matching rule}

{If Scan Profile fix:} Update [Scan Profile](https://docs.endor.ai/docs/scan-profiles/) with correct toolchain version.
{If Private Registry fix:} Configure [Private Package Registry](https://docs.endor.ai/docs/integrations/private-package-registries), or set credentials in CI.
{If not fixable in cloud:} Move scanning to CI/CD pipeline.

### Next Steps
- `/endor-scan` - Re-run after fix
- `/endor-setup` - Reconfigure if needed

Step 5: Handle Multiple Errors

1. Identify all distinct errors
2. Diagnose each separately
3. Present in priority order: Private Registry > Toolchain > Other
4. Note if fixing one may resolve others

Common Resolution Patterns

Auth Conflict: Check if ~/.endorctl/config.yaml exists AND settings.json/mcp.json contains auth env vars. If both present, user must choose one workflow:

• Local Development: keep config.yaml, remove ENDORMCPSERVERAUTHMODE/ENDORNAMESPACE/ENDORAPI from settings.json env block
• Multi-Namespace: delete ~/.endorctl/config.yaml (or rm -rf ~/.endorctl), keep env vars in settings.json

Then restart MCP connection and retry. See /endor-setup Step 2.2 for full workflow details.

Private Registry: Check if package is private -> configure Private Package Registry or set CI credentials -> verify registry is internet-accessible from cloud.

Toolchain: Identify required version from error -> update Scan Profile -> re-scan.

Cloud Scanning Limitations (move to CI): SSH Git deps, system package installation (python3-dev, PostgreSQL libs), Windows builds, custom env vars, Docker builds.

For data source policy, read references/data-sources.md.

Error Handling