Aspect Code logoAspect Code

Troubleshooting

Common issues and how to resolve them.

KB didn't generate / stuck scanning

If the knowledge base isn't generating or appears stuck:


Check the output panel:

  • Open the Output panel (View → Output)
  • Select "Aspect Code" from the dropdown
  • Look for error messages or stack traces

    • Common causes:

  • Very large workspace — For monorepos with thousands of files, initial scan can take several minutes. The panel shows progress.
  • Unsupported file types only — Aspect Code works best with TypeScript, JavaScript, Python, Java, and C#. If your workspace only contains other languages, the KB may be minimal.
  • Extension not activated — Try running "Aspect Code: Show Panel" from the Command Palette to ensure the extension is active.

    • Try a force reindex:

    Run "Aspect Code: Force Reindex (Clear Cache)" from the Command Palette to clear cached analysis and start fresh.

    No files appear / empty KB

    If no files appear in the dependency graph or the KB is empty:


    Check file types:

    Aspect Code currently analyzes: TypeScript (.ts, .tsx), JavaScript (.js, .jsx), Python (.py), Java (.java), and C# (.cs).


    Check workspace root:

    The extension analyzes files from the workspace root. If your code is in a subdirectory, open that folder directly in VS Code.


    Check .gitignore:

    Files matching patterns in .gitignore may be excluded from analysis. Check if your source files are accidentally ignored.


    Check for errors:

    Run "Aspect Code: Copy Debug Info" and check the output for any error messages.

    Monorepo detection issues

    For large monorepos:


    Scope to specific directories:

  • Open a specific package/project folder directly in VS Code instead of the entire monorepo root
  • Or use Custom mode to add instructions scoping analysis to specific paths

    • Performance tips:

  • Initial scan of large monorepos can take a few minutes
  • The panel shows file/dependency counts during scanning
  • Subsequent regenerations are faster due to caching

    • Multiple workspaces:

    If you have a VS Code multi-root workspace, Aspect Code analyzes each workspace root separately.

    How to fully remove Aspect Code

    To completely remove Aspect Code:


    1. Uninstall the extension:

  • Open Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  • Find "Aspect Code"
  • Click Uninstall

    • 2. Remove generated files (optional):

    Delete any generated files you don't want to keep:

    # Remove KB folder
rm -rf .aspect/

# Remove assistant instruction files (if generated)
rm -f CLAUDE.md
rm -f AGENTS.md
rm -rf .cursor/rules/aspectcode.mdc

# For copilot-instructions.md, you may want to edit rather than delete
# if you have other content in that file

    3. Clean up .gitignore (optional):

    Remove any Aspect Code entries from your .gitignore if they were added.

    Where logs are / how to report a bug

    View logs:

  • Open the Output panel (View → Output or Ctrl+Shift+U / Cmd+Shift+U)
  • Select "Aspect Code" from the dropdown
  • For verbose logging, enable aspectcode.devLogs in settings

    • Copy debug info:

    Run "Aspect Code: Copy Debug Info" to copy diagnostic information including:

  • Extension version
  • VS Code version
  • Workspace statistics
  • Current settings
  • Recent errors

    • Report a bug:

  • Copy debug info using the command above
  • Open an issue at github.com/asashepard/aspectcode/issues
  • Include:

    • - What you expected to happen

    - What actually happened

    - Steps to reproduce

    - Debug info (without any sensitive data)


    Contact directly:

    Email asa@aspectcode.com for support.

    Instruction files not updating

    If instruction files aren't updating after regeneration:


    Check configured assistants:

    Run "Aspect Code: Configure AI Assistants" to ensure your assistants are selected.


    Check instruction mode:

    Make sure the instruction mode isn't set to "Off". Check the panel or run "Aspect Code: Enable Safe Mode".


    Manual regeneration:

    Click the refresh button in the panel or run "Aspect Code: Generate Instruction Files" from the Command Palette.


    Check file permissions:

    Ensure VS Code has write permission to the generated file locations.

    Generated Files