# How to Debug SkillSpector Scan Failures with Verbose Logging

> Debug SkillSpector scan failures effectively. Enable verbose logging with --verbose or SKILLSPECTOR_LOG_LEVEL=DEBUG for detailed traces and error analysis. Resolve issues faster.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-06-24

---

**Enable the `--verbose` flag or set `SKILLSPECTOR_LOG_LEVEL=DEBUG` to expose detailed execution traces, node transitions, and error stack traces from the LangGraph workflow.**

When a scan fails in NVIDIA SkillSpector—whether it crashes with a non-zero exit code, fails to resolve an input path, or returns unexpected risk scores—the fastest way to diagnose the issue is to inspect the internal execution flow. SkillSpector uses a structured logging system that captures every step of the analysis pipeline, from input resolution to LLM provider calls. Verbose logging reveals exactly which node in the graph failed and why.

## How Verbose Logging Works in SkillSpector

### The CLI Verbose Flag

In [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), the `scan` command defines a `--verbose` (or `-V`) option. When invoked, the CLI calls `set_level("DEBUG")` from the logging module, raising the root logger’s level from **WARNING** to **DEBUG**. This single call propagates verbose output across all modules in the package.

```bash
skillspector scan ./my-skill --verbose

```

### Centralized Logging Configuration

The logging infrastructure lives in [`src/skillspector/logging_config.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/logging_config.py). The `get_logger(__name__)` function returns a package-scoped logger (format: `skillspector.<module>`) configured once per process. When the level is set to `DEBUG`, every handler emits detailed messages, ensuring that modules like `skillspector.nodes.resolve_input` or `skillspector.nodes.analyzers.static_yara` output their internal state.

All primary nodes—including `resolve_input`, `build_context`, each analyzer, `meta_analyzer`, and `report`—obtain their loggers via `get_logger(__name__)`. Consequently, enabling verbose mode surfaces granular details about file handling, YARA rule compilation, and LLM API interactions.

## Understanding the Scan Execution Flow

SkillSpector executes scans as a **LangGraph workflow**. The CLI builds an initial state dictionary (`_scan_state`) and invokes the compiled graph via `graph.invoke(state, config=trace_config)` in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py). The graph wires nodes in a deterministic order: resolve input → build context → run analyzers → meta-analysis → generate report.

Debug logs reveal the exact sequence of node invocations and intermediate state payloads. When an exception occurs, the graph’s exception handling prints the full traceback alongside the node name in the log prefix (e.g., `skillspector.nodes.analyzers.static_yara`), making it trivial to pinpoint the failure point.

## Common Failure Patterns and Debug Log Analysis

Verbose output exposes specific error categories:

- **File-not-found or bad URL**: Look for "Error loading..." messages in `resolve_input` node logs at DEBUG level.
- **YARA rule compilation errors**: The `build_context` node logs "Failed to compile YARA rule..." with the offending file path.
- **LLM provider misconfiguration**: Provider modules emit "Provider <name> missing API key" or HTTP error details from files in `src/skillspector/providers/`.
- **Analyzer exceptions**: Individual analyzers under `src/skillspector/nodes/analyzers/` print tracebacks when unexpected errors occur.
- **Non-zero exit codes**: The CLI prints the final `risk_score` before calling `raise typer.Exit(code=1)`; debug logs show the score calculation and any intermediate warnings.

## Enabling Debug Logging

### Using the Command-Line Flag

The most direct method to debug SkillSpector scan failures with verbose logging is the `--verbose` flag:

```bash
skillspector scan ./my-skill --verbose

```

You will see output similar to:

```

DEBUG [skillspector.graph] Scan started: input_path=./my-skill, format=terminal, use_llm=True
DEBUG [skillspector.nodes.resolve_input] Resolving input path ./my-skill …
DEBUG [skillspector.nodes.build_context] Loading YARA rules from /usr/share/skillspector/yara …
DEBUG [skillspector.nodes.analyzers.static_yara] Running YARA scan on 12 files …
DEBUG [skillspector.providers.openai.provider] Calling OpenAI API model=gpt-4 …

```

### Using Environment Variables

If you cannot modify the command line (e.g., when SkillSpector is invoked by another script), set the `SKILLSPECTOR_LOG_LEVEL` environment variable. The [`src/skillspector/logging_config.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/logging_config.py) file reads this variable during initialization, treating `DEBUG` the same as the `--verbose` flag.

```bash
export SKILLSPECTOR_LOG_LEVEL=DEBUG
skillspector scan ./my-skill

```

Or inline:

```bash
SKILLSPECTOR_LOG_LEVEL=DEBUG skillspector scan https://github.com/example/bad-skill

```

### Capturing Logs to File

To analyze failures offline, redirect stderr to a file:

```bash
skillspector scan ./my-skill --verbose 2>debug.log

```

Then filter for specific nodes:

```bash
grep "static_yara" debug.log
grep "resolve_input" debug.log

```

## Key Source Files for Debugging

| File | Role |
|------|------|
| [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) | CLI definition, handles `--verbose`, builds `_scan_state`, and invokes the graph |
| [`src/skillspector/logging_config.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/logging_config.py) | Central logging configuration, reads `SKILLSPECTOR_LOG_LEVEL` |
| [`src/skillspector/graph.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/graph.py) | Constructs the LangGraph workflow with all analyzer nodes |
| [`src/skillspector/nodes/resolve_input.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/resolve_input.py) | Resolves file paths, URLs, and ZIP archives |
| [`src/skillspector/nodes/build_context.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/build_context.py) | Loads YARA rules and prepares analysis context |
| `src/skillspector/nodes/analyzers/*.py` | Individual analyzers (e.g., [`static_yara.py`](https://github.com/NVIDIA/SkillSpector/blob/main/static_yara.py)) |
| `src/skillspector/providers/*` | LLM provider implementations (OpenAI, Anthropic, NVIDIA) |

## Summary

- **Enable verbose mode** with `--verbose` or `SKILLSPECTOR_LOG_LEVEL=DEBUG` to raise the logger level from WARNING to DEBUG.
- **Trace the execution flow** through the LangGraph workflow, watching state transitions between `resolve_input`, `build_context`, analyzers, and `meta_analyzer`.
- **Identify failure points** by examining node-specific log prefixes and stack traces in the debug output.
- **Capture output** to files for offline analysis using shell redirection.

## Frequently Asked Questions

### How do I enable verbose logging in SkillSpector?

Add the `--verbose` (or `-V`) flag to any `skillspector scan` command. This calls `set_level("DEBUG")` in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), which configures the root logger to emit DEBUG-level messages from all nodes and providers.

### What does the SKILLSPECTOR_LOG_LEVEL environment variable do?

Setting `SKILLSPECTOR_LOG_LEVEL=DEBUG` before running SkillSpector achieves the same effect as `--verbose`. The [`src/skillspector/logging_config.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/logging_config.py) module checks this variable during startup and configures the logger accordingly, making it useful when you cannot modify the command line directly.

### Where are the analyzer logs located in SkillSpector?

SkillSpector does not write logs to disk by default; they stream to stderr. To save analyzer logs, run the scan with verbose mode and redirect stderr to a file: `skillspector scan ./project --verbose 2>logs.txt`. The analyzers in `src/skillspector/nodes/analyzers/` emit logs under the `skillspector.nodes.analyzers` namespace.

### How can I debug a specific analyzer node failure?

Enable verbose logging and grep the output for the specific analyzer name (e.g., `grep "static_yara"` or `grep "meta_analyzer"`). The debug output includes the full traceback and the node name prefix (e.g., `skillspector.nodes.analyzers.static_yara`), allowing you to isolate whether the failure stems from YARA compilation, LLM API calls, or state handling.