# Malware troubleshooting

The errors and warnings vulnetix malscan prints, scans that checked nothing, false positives, and the fix for each.

Use this page when `vulnetix malscan` stops with an error, reports `INCOMPLETE`, or flags a package you trust. Errors print as `Error: <message>` on stderr. [Exit codes](/malware/reference/output.md#exit-codes) are on the output page.

## Starting a scan

| Symptom or message | Cause | Fix |
|---|---|---|
| `--output must be one of: pretty (alias: table), json, sarif` | `-o` here is one stdout format, not a file path | Use `-o json` or `-o sarif`, and `--output-file <path>` for the file. See [Flags](/malware/reference/flags.md#output). |
| `--feeds is only used with --fetch-definitions` | `--feeds` on a scan | Add `--fetch-definitions`; `--feeds` changes the refresh, not the scan. |

## Nothing checked, or no definitions

| Symptom or message | Cause | Fix |
|---|---|---|
| `INCOMPLETE` with `none installed under this path, so there was nothing to inspect` | No install directories under the scan root | Install dependencies first (`npm ci --ignore-scripts`, `pip install`, ...). malscan reads what is installed. See [Scan targets](/malware/reference/scan-targets.md). |
| `INCOMPLETE` with `the install directories held no packages or files` | The directories exist but are empty | Install, then scan again. |
| `INCOMPLETE` with `no known-bad indicator definitions are loaded to compare against` | The feeds were not fetched and no cache exists | Run `vulnetix malscan --fetch-definitions` once. See [Threat-intel definitions](/malware/guides/threat-intel.md#refresh). |
| `iocscan(<eco>): feeds unavailable: <error>` | The STIX feeds could not be downloaded | The detect and badhash families still ran. For air-gapped hosts, copy the definitions directory. See [Offline and air-gapped](/malware/guides/threat-intel.md#offline-and-air-gapped). |
| The wrong directory was scanned | With no `--path`, the root is the git root, not the current directory | Pass `--path` or a positional path. |
| Go, Java, .NET, Dart or Elixir packages get no pattern findings | Only the IOC scan runs for those ecosystems | Expected. See [Detectors](/malware/reference/detectors.md#families). |
| `no threat-intel feeds could be fetched (<n> failed); definitions left unchanged` | `--fetch-definitions` reached none of the feeds | Exits `1`. Check outbound access; the existing definitions are kept. |

> [!CAREFUL] INCOMPLETE exits 0
> A scan that checked nothing returns `0`, like a clean one. In CI, install dependencies before the scan and check for `INCOMPLETE`.

## False positives and the gate

| Symptom or message | Cause | Fix |
|---|---|---|
| `quality gate(s) breached: malscan: N malware findings (<packages>)` | A package has at least one evidence finding | Remove it and rotate what its install script could read. If you are sure it is wrong, see the rows below. See [Detection model](/malware/guides/detection-model.md). |
| An indicator is wrong for everyone | The feed or a curated IOC is a false positive | Mark it false positive in the Resolve Platform. One decision clears it for every customer. See [Curation](/malware/guides/curation.md). |
| One finding is accepted for one repository | The finding is real but acceptable here, or the false positive is local | `vulnetix ignore add --category malware --rule <id> --file <path>`. See [Suppressing findings](/malware/guides/suppression.md). |
| A package-version false positive in the Resolve Platform did not stop local findings | Package-version decisions do not filter local findings | Add an ignore rule for that repository. |
| A detector is noisy for one ecosystem | A pattern section or detector fires on packages you trust | Turn the capability off with `--catalog`. See [Turning detectors off](/malware/reference/detectors.md#turning-detectors-off). |
| `/v2/cli.malscan chunk 1/1 submit failed: <error>` | The upload failed | Check the credential with `vulnetix auth verify`, or pass `--no-upload`. |

## Still stuck

Collect the CLI version (`vulnetix version`), the exact command, its output with `-v`, the `warnings` in `runs[0].properties` of `.vulnetix/malscan.sarif` (or `-o json`), and `.vulnetix/memory.yaml` if an ignore rule is involved. Note where the definitions directory is and when `--fetch-definitions` last ran. For sign-in and upload errors, start with [Troubleshooting authentication](/cli/authentication/troubleshooting.md).
