> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging

## Plugin errors

A plugin error indicates that a plugin exited with a status code that is interpretted as an error. This can occur for a number of different reasons. For example, some linters will crash if they attempt to analyze files with invalid syntax.

<Note>
  Some linters exit with a non-zero code when they find issues. Qlty treats these exit codes as
  *success* to differentiate the case where a plugin ran successfully identified issues vs. a
  crash or unexpected failure.
</Note>

### Verbose and debug output

Typically the first step to investigating a plugin error is to re-run the plugin with verbose or debug output enabled. Here is an example:

```sh lines theme={"system"}
qlty check --all --verbose --debug --filter=stylelint
```

The `--debug` option will increase the amount of detail in the logs going to `.qlty/logs/qlty-cli.*`. You can tail this log as you run the CLI to watch for issues with `tail -f .qlty/logs/qlty-cli.*`.

The `--verbose` option will cause the CLI to print a summary of every invocation (execution) of the plugin from the run. The full details of each invocation are recorded in an output file saved to the `.qlty/out/` directory. Here is an example:

```yaml maxLines=10 lines theme={"system"}
qlty_cli_version: 0.319.0
invocation_id: LaW4ba
plugin_name: markdownlint
driver_name: lint
verb: Check
config_files:
    - /Users/username/p/qltysh/qlty/.qlty/configs/.markdownlint.json
    - /Users/username/p/qltysh/qlty/.markdownlint.json
script: sh -c "markdownlint --json fern-public/fern/docs/pages/cloud/additional-information/faq.mdx"
env:
    PATH: /Users/username/.qlty/cache/tools/markdownlint/0.41.0-a8b86ee94758/node_modules/.bin:/Users/username/.qlty/cache/tools/node/19.6.0-cac67db15d71/bin:/Users/username/.qlty/cache/tools/node/19.6.0-cac67db15d71:/Users/username/.qlty/cache/tools/node/19.6.0-cac67db15d71/bin:/Users/username/.qlty/cache/tools/node/19.6.0-cac67db15d71:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
    HOME: /Users/username
    NODE_PATH: /Users/username/.qlty/cache/tools/markdownlint/0.41.0-a8b86ee94758/node_modules
cwd: /Users/username/p/qltysh/qlty
duration_secs: 0.187106333
exit_result: Success
exit_code: 1
stdout: ""
stderr: |
    [
      {
        "fileName": "fern-public/fern/docs/pages/cloud/additional-information/faq.mdx",
        "lineNumber": 5,
        "ruleNames": [
          "MD041",
          "first-line-heading",
          "first-line-h1"
        ],
        "ruleDescription": "First line in a file should be a top-level heading",
        "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md041.md",
        "errorDetail": null,
        "errorContext": "## Can I use Qlty without the ...",
        "errorRange": null,
        "fixInfo": null
      }
    ]
tmpfile_path: null
tmpfile_contents: null
parser_error: null
```

From this file you can see the exact command that was run, the environment variables that were set, and the output that was produced. If any errors occurred, they will be included.

### `Could not find "[package-name]"` (Missing plugin extension)

A common error is that a plugin may be missing an extension references in its configuration. For example:

```
Lint error stylelint: Exited with code 78 .qlty/out/invoke-tPeFXQ.yaml
        Error: Could not find "@blueprintjs/stylelint-plugin". Do you need a `configBasedir`?
            at module.exports (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/utils/configurationError.js:11:49)
            at getModulePath (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/utils/getModulePath.js:28:9)
            at /Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/augmentConfig.js:153:60
            at Array.map (<anonymous>)
            at absolutizePaths (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/augmentConfig.js:153:44)
            at Object.transform (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/augmentConfig.js:81:27)
            at runLoad (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/cosmiconfig/dist/Explorer.js:104:49)
            at async cacheWrapper (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/cosmiconfig/dist/cacheWrapper.js:16:18)
            at async extendConfig (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/augmentConfig.js:201:24)
            at async augmentConfigBasic (/Users/username/.qlty/cache/tools/stylelint/14.6.1-a7e99b04b5e3/node_modules/stylelint/lib/augmentConfig.js:52:20)
```

This error indicates that the Stylelint plugin was unable to load `@blueprintjs/stylelint-plugin`. The reason that this would happen is because the Qlty CLI installs static analysis tools into sandboxes in order to create conssitent, reporducible results whereever it is run.

When an erorr like this occurs, you will generally find that the references package (in this case, `@blueprintjs/stylelint-plugin`) is included in the project's `package.json` file. By default, we do not install the packages in the `package.json` file when we run analysis.

There are a three ways to fix this:

<AccordionGroup>
  <Accordion title="Option 1: Use the `extra_packages` option">
    Specify the `extra_packages` option for the plugin in `qlty.toml`. Any listed packages will be installed into the tool's sandbox making them available. Here is an example:

    ```toml lines theme={"system"}
    [[plugin]]
    name = "stylelint"
    version = "14.16.1"
    extra_packages = ["stylelint-config-standard-scss@11.0.0"]
    ```

    This tells Qlty to install `stylelint-config-standard-scss@11.0.0` into the sandbox for the `stylelint` plugin before running. This syntax works for simple cases and has the benefit of keeping the dependency declaration directly inline with the plugin configuration.
  </Accordion>

  <Accordion title="Option 2: Point the `package_file` option at your existing package.json">
    This will cause Qlty to install all of the packages in the `package.json` file into the sandbox for the plugin. Here is an example:

    ```toml lines theme={"system"}
    [[plugin]]
    name = "stylelint"
    version = "14.16.1"
    package_file = "package.json"
    ```

    If you are using a lot of extensions for your static analysis tools, this is a good way to get up and running quickly. The primary disadvantage is that all of the dependencies need to be installed before static analysis can be run, which can slow things down.
  </Accordion>

  <Accordion title="Option 3: Create a new package.json limited to static analysis tools">
    This allows you to install all the extensions you need quickly and can allow you to de-clutter your main `package.json` file. Here is an example:

    ```sh lines theme={"system"}
    cd .qlty/configs
    echo '{}' > package.json
    npm install --save-dev stylelint-config-standard-scss
    ```

    ```toml lines theme={"system"}
    [[plugin]]
    name = "stylelint"
    version = "14.16.1"
    package_file = ".qlty/configs/package.json"
    ```
  </Accordion>
</AccordionGroup>

You can read more about this at [linter extensions page](/cli/linter-extensions).

### `Could not find "[config file].[json]"` (Missing configuration file)

If you have a static analysis configuration file that is not using one of the tool's standard configuration filenames, Qlty needs to know about it. Otherwise, you will see errors like this:

```
Error: Could not find "../../../../shared/stylelintrc.shared.json". Do you need a `configBasedir`?
```

The fix is to make the Qlty CLI aware of the configuration filename, in this case `stylelintrc.shared.json`. To do this, you need to override the *definition* of the Stylelint plugin to include all of the configuration file names you use in your project.

For example, you can add this towards the top of your `.qlty/qlty.toml` file:

```toml lines theme={"system"}
[plugins.definitions.stylelint]
config_files = [
  ".stylelintrc",
  ".stylelintrc.cjs",
  ".stylelintrc.js",
  ".stylelintrc.json",
  ".stylelintrc.yaml",
  ".stylelintrc.yml",
  "stylelintrc.shared.json", # Custom, shared configuration file
]
```

This will cause Qlty to ensure that all of those listed configuration files, including the custom, shared configuration file, are properly made available to the plugin.

## Plugin parser errors

A parse error indicates that Qlty was unable to process the results output by the plugin. This can happen is a static analysis tool changes its output format.

If you encounter a parse error with a plugin, please contact support for assistance.