> For the complete documentation index, see [llms.txt](https://docs.viesus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viesus.com/support/troubleshooting.md).

# Troubleshooting

Symptom-based fixes spanning the first run and every interface. For specific exit/error codes, see [Error Codes](/support/error-codes.md).

<button type="button" class="button secondary" data-action="ask" data-query="Help me diagnose a VIESUS problem. My symptom is: " data-icon="gitbook-assistant">Diagnose my issue</button>

***

## Quick fixes

| Symptom                | First thing to try                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `viesus` not found     | Add the VIESUS install dir to `PATH`, or restart your terminal                     |
| GUID not accepted      | Confirm the library version matches the install (`viesus -v`)                      |
| License rejected       | Re-run the license activation and restart the system                               |
| CLI hangs              | Check disk space at the output path; restart if needed                             |
| Slow processing        | Check disk I/O, use local storage, run multiple instances rather than more threads |
| No output produced     | Pass an output flag (`-s`, `-b`, or `-n`) — the CLI writes nothing without one     |
| Output looks unchanged | Set `SKIPmode: 0` and `Enhancemode: 1`; test with a clearly low-quality image      |

***

## First run

The issues that most commonly block a first install and first run.

### Installation failed or gave a warning

**Windows — "Windows protected your PC":** Click **More info** → **Run anyway**. The installer is signed by Viesus AG; SmartScreen blocks it because it's not a widely-distributed consumer application.

**Windows — installer fails silently:** Right-click the `.exe` → **Run as administrator**. The installer requires elevated privileges.

**Linux — dependency error during `dpkg -i`:**

```bash
sudo apt-get install -f
```

This resolves any missing shared library dependencies left over from the `.deb` install.

### `viesus: command not found`

The VIESUS executable installs at `/usr/local/viesus/viesus`, which is not on `PATH` by default.

**Run directly:**

```bash
/usr/local/viesus/viesus -v
```

**Add to PATH permanently (Linux):**

```bash
echo 'export PATH="/usr/local/viesus:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**Windows:** run from the VIESUS Viewer installation directory, or add it to the system PATH via System Properties → Environment Variables.

### GUID error on first run

```
Error: GUID wrong
```

1. Check for extra spaces — copy the GUID directly from your delivery email; do not type it.
2. Verify the GUID matches the library package you installed (the same GUID must come from the same delivery).
3. Wrap the GUID in quotes to avoid shell interpretation issues: `-g "your-guid-here"`.

### No output files produced

If `viesus` completes silently but no output images appear, check which output mode you specified:

| You want                                     | Add this flag           |
| -------------------------------------------- | ----------------------- |
| Output alongside input with `_viesus` suffix | `-s`                    |
| Output in a specific folder                  | `-b /path/to/output -s` |
| Custom suffix                                | `-n "_mysuffix"`        |

The CLI does not produce output without one of these flags — this is intentional.

### Images processed but look unchanged

* **`SKIPmode` is active:** `SKIPmode: 1` skips images VIESUS considers already enhanced — set `"SKIPmode": 0`.
* **`Enhancemode` is off:** set `"Enhancemode": 1`.
* **License expired:** VIESUS passes images through without enhancement. Check result files — `"ieApplied": 0` confirms enhancement did not run. Contact <info@viesus.com> to renew.
* **Input is already high quality:** VIESUS applies proportional corrections — minor input issues mean minor output change. Test with a clearly underexposed or noisy image.

***

## CLI and image enhancement

Runtime issues with the CLI and Viewer. For first-run/setup problems, see [First run](#first-run) above; for the full exit-code catalogue, see [CLI Exit Codes](/support/error-codes/cli.md).

### Very slow processing; GPU features not running

1. Check the NVIDIA driver: `nvidia-smi` must show CUDA version ≥ 12.6.
2. Verify AI features are enabled in `viesusini.json` (`ARmode: 1`, `ResizeMode: 10`, etc.) — they default to off.
3. Confirm the GPU add-on packages are installed (`viesus-sr`, `viesus-ar`, `viesus-bg`).
4. In Docker: verify `--gpus all` is passed and the NVIDIA Container Toolkit is installed.
5. Ensure no other instance (such as the Viewer) is running and holding the GPU.

Single-threaded processing is fastest per image (cache locality); parallelism comes from running multiple CLI instances, not from raising the thread count inside one. See [Benchmarks](/operations/benchmarks.md).

### Out of memory (OOM) errors

Reduce the number of parallel processes or workers. Each VIESUS worker with AI features needs 4–8 GB RAM plus GPU VRAM.

* **CLI:** reduce parallel invocations.
* **Node.js:** reduce `UV_THREADPOOL_SIZE`.
* **PDF Enhancer:** reduce `threads` in `settings.json` and `maxTargetSize`.

### Permission denied

Ensure write access to the output directory and exclusive read access to the input file (check that no other process has it open).

### Invalid configuration / JSON

* Validate JSON syntax — many editors silently leave trailing commas: `python -m json.tool < viesusini.json`.
* Check values are within range — see the [Parameter Reference](/configuration/parameter-reference.md).
* For unexpected results, start from a known-good [preset](/configuration/presets-gallery.md) and change one parameter at a time.

### Output images have an unexpected format

VIESUS writes output only when an output flag (`-s`, `-b`, or `-n`) is passed, and the path must use a supported extension. Supported output formats are `.jpg`, `.png`, and `.tif` — ensure your configured output path uses one of them.

### Licensing errors

License-related exit codes (`-90` to `-95` GUID errors, `-50` feature not licensed, `-70` daily limit) are catalogued in [CLI Exit Codes](/support/error-codes/cli.md).

***

## PDF Enhancer

### PDF processed but no images enhanced

1. Run with `justAnalyze: 1` in settings or the `-t` flag to check what images VIESUS detects.
2. Check `minImageWidth`, `minImageHeight`, `minFileSize` — images below these thresholds are skipped.
3. Check `skipFullPageBackground` — full-page background images are excluded when enabled.
4. Check `useColorRatio` — low-color-variation images (gradients, solid fills) may be filtered.

### XML report shows error code other than 0

See [PDF Error Codes](/support/error-codes/pdf.md) for the full table and solutions. Common errors:

* Code 7: input PDF not found — check the source path
* Code 12/14: output write failure — check destination folder permissions and disk space
* Code 20/26: VIESUS processing error — check the GUID and library installation

### Hotfolder not picking up new PDFs

1. Verify the `sourceFolder` path in `settings.json` is correct and accessible.
2. Check `triggerSuffix` — only files matching the suffix are picked up (default `.pdf`).
3. Check `pollInterval` — new files appear after the next poll.
4. Confirm the `viesusPDF` process is running: `ps aux | grep viesusPDF`

***

## Node.js module

### `Error: Cannot find module 'viesus'`

The native module is not installed. Install it:

```bash
sudo npm install /usr/local/viesus/node-viesus
```

Verify installation:

```bash
node -e "const v = require('viesus'); console.log('ok')"
```

### `Enhance()` returns a negative code

Look up the code in [Node.js API Reference: Error Codes](/reference/node.js-module/api-reference.md#error-codes). Common ones:

| Code          | Cause                             | Fix                                                    |
| ------------- | --------------------------------- | ------------------------------------------------------ |
| `-2` / `-378` | Wrong GUID                        | Check the GUID string                                  |
| `-4`          | Cannot load input image           | Verify the input file exists and is a supported format |
| `-5` / `-6`   | Cannot open file                  | Check file paths are absolute and accessible           |
| `-10` / `-11` | Parameter file not found or empty | Verify `iniPath` points to a valid `viesusini.json`    |
| `-13`         | Cannot write result file          | Check that the output directory exists and is writable |

### Workers initializing slowly

`MyViesusObject` initialization (first call per worker) loads the VIESUS engine and any enabled AI models. This is expected — 1–10 seconds per worker at startup depending on enabled features and hardware. Subsequent `Enhance()` calls are fast.

Do not create a new `MyViesusObject` per image. Create one per worker thread at startup and reuse it.

### Pool is saturated (high queue wait time)

The `wallMs` time in logs is much higher than `enhanceMs` — jobs are waiting in the queue for a free worker. Solutions:

* Increase `UV_THREADPOOL_SIZE` (up to available CPU cores)
* Add more hardware (CPU cores or GPUs)
* Reduce AI feature usage to speed up per-image time

***

## VIESUS Cloud

### API returns authentication error

1. Verify your API key is correct — copy it fresh from the dashboard.
2. Confirm the `x-api-key` header is spelled exactly right (lowercase).
3. Confirm the request goes to `https://api.viesus.cloud/graphql`.

### Enhancement status stuck at `QUEUED`

Normal for up to several minutes under load. If queued for > 10 minutes:

1. Check the API status page (if available).
2. Try creating a new enhancement — it may be a transient issue with that specific job.
3. Contact <info@viesus.com> with the enhancement ID.

### Webhook not receiving events

1. Verify your endpoint is publicly accessible — VIESUS Cloud cannot reach localhost.
2. Check your endpoint returns `2xx` — non-2xx responses are retried.
3. Query webhook logs for delivery history: see [Webhooks](/reference/cloud-api/webhooks.md#webhook-logs).
4. Confirm the webhook `url` in the `createWebhook` mutation was correct.

### PDF analysis fails repeatedly

Try re-triggering analysis:

```graphql
mutation {
  analyzePdf(uploadId: "your-upload-id") {
    success
  }
}
```

If it continues to fail, the PDF may be password-protected, corrupted, or contain no raster images. Contact <info@viesus.com> with the upload ID.

***

## Getting support

Contact <info@viesus.com> and include:

* VIESUS version: `viesus -v` (CLI) or the installed package version
* Platform: OS, architecture, CPU/GPU model
* Interface: CLI, PDF Enhancer, Node.js, Cloud
* Error codes or XML report content
* What you expected vs. what happened
* A sample image or PDF if the issue is content-specific (share privately if needed)

For Cloud API issues, include the `uploadId` or `enhancementId` from the API response.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.viesus.com/support/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.