Debugging | Qlty Docs

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.

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.

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:

1 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:

1 qlty_cli_version: 0.319.0
2 invocation_id: LaW4ba
3 plugin_name: markdownlint
4 driver_name: lint
5 verb: Check
6 config_files:
7     - /Users/username/p/qltysh/qlty/.qlty/configs/.markdownlint.json
8     - /Users/username/p/qltysh/qlty/.markdownlint.json
9 script: sh -c "markdownlint --json fern-public/fern/docs/pages/cloud/additional-information/faq.mdx"
10 env:
11     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
12     HOME: /Users/username
13     NODE_PATH: /Users/username/.qlty/cache/tools/markdownlint/0.41.0-a8b86ee94758/node_modules
14 cwd: /Users/username/p/qltysh/qlty
15 duration_secs: 0.187106333
16 exit_result: Success
17 exit_code: 1
18 stdout: ""
19 stderr: |
20     [
21       {
22         "fileName": "fern-public/fern/docs/pages/cloud/additional-information/faq.mdx",
23         "lineNumber": 5,
24         "ruleNames": [
25           "MD041",
26           "first-line-heading",
27           "first-line-h1"
28         ],
29         "ruleDescription": "First line in a file should be a top-level heading",
30         "ruleInformation": "https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md041.md",
31         "errorDetail": null,
32         "errorContext": "## Can I use Qlty without the ...",
33         "errorRange": null,
34         "fixInfo": null
35       }
36     ]
37 tmpfile_path: null
38 tmpfile_contents: null
39 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:

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:

1 [[plugin]]
2 name = "stylelint"
3 version = "14.16.1"
4 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.

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:

1 [[plugin]]
2 name = "stylelint"
3 version = "14.16.1"
4 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.

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:

1 cd .qlty/configs
2 echo '{}' > package.json
3 npm install --save-dev stylelint-config-standard-scss

1 [[plugin]]
2 name = "stylelint"
3 version = "14.16.1"
4 package_file = ".qlty/configs/package.json"

`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:

1 [plugins.definitions.stylelint]
2 config_files = [
3   ".stylelintrc",
4   ".stylelintrc.cjs",
5   ".stylelintrc.js",
6   ".stylelintrc.json",
7   ".stylelintrc.yaml",
8   ".stylelintrc.yml",
9   "stylelintrc.shared.json", # Custom, shared configuration file
10 ]

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.

Plugin errors

Verbose and debug output

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

Option 1: Use the extra_packages option

Option 2: Point the package_file option at your existing package.json