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/invocations/ 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/invocations/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

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

Option 3: Create a new package.json limited to static analysis tools

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

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

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	]