Troubleshooting

Symptom-based fixes for VIESUS — first-run and install blockers, plus CLI, PDF Enhancer, Node.js module, and VIESUS Cloud issues.

Symptom-based fixes spanning the first run and every interface. For specific exit/error codes, see Error Codes.

---

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:

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:

/usr/local/viesus/viesus -v

Add to PATH permanently (Linux):

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 [e-mail] 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 above; for the full exit-code catalogue, see CLI Exit Codes.

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.

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.
• For unexpected results, start from a known-good preset 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.

---

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

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

Verify installation:

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. 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 [e-mail] 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.
4. Confirm the webhook url in the createWebhook mutation was correct.

PDF analysis fails repeatedly

Try re-triggering analysis:

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 [e-mail] with the upload ID.

---

Getting support

Contact [e-mail] 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.