> 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/error-codes/pdf.md).

# PDF Enhancer Error Codes

Error codes appear in the XML processing report (`<error code="X" msg="..."/>`). Code `0` means success; all non-zero codes indicate a processing failure.

For underlying CLI exit codes from the enhancement engine, see [CLI Exit Codes](/support/error-codes/cli.md). For settings-related issues, see the PDF [Settings Reference](/configuration/pdf-settings.md).

<button type="button" class="button secondary" data-action="ask" data-query="What does VIESUS PDF Enhancer error code ___ mean, and how do I fix it?" data-icon="gitbook-assistant">Explain a PDF error</button>

***

<details>

<summary><strong>Common fixes by category</strong></summary>

**File system issues (12, 14–18)**

* Verify all file and folder paths exist
* Check read / write permissions
* Ensure sufficient disk space

**Permission errors (21–22)**

* Run with appropriate user privileges
* Check file / folder permissions
* Ensure exclusive access to files

**PDF processing (6, 13, 23–28)**

* Verify PDF file integrity
* Check for password protection
* Confirm PDF version compatibility

**License (7, 36)**

* Verify license validity and expiration
* Check processing limits
* Contact <info@viesus.com>

</details>

<details>

<summary><strong>General system errors (1–8)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>An unknown or unspecified error occurred</td></tr><tr><td>2</td><td>The PDF file has already been enhanced (use force option to re-process)</td></tr><tr><td>3</td><td>Failed to load the configuration/settings file</td></tr><tr><td>4</td><td>Unable to open the PDF document (file may be corrupted or password-protected)</td></tr><tr><td>5</td><td>Failed to create required directories</td></tr><tr><td>6</td><td>The input file is not a valid PDF document</td></tr><tr><td>7</td><td>License validation failed or license is invalid</td></tr><tr><td>8</td><td>PDF library initialisation or operation failed</td></tr></tbody></table>

</details>

<details>

<summary><strong>File system &#x26; path errors (9, 12, 14–18)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>9</td><td>File size is below the minimum threshold for processing</td></tr><tr><td>12</td><td>The specified input file could not be found</td></tr><tr><td>14</td><td>The specified path does not exist</td></tr><tr><td>15</td><td>VIESUS configuration file not found</td></tr><tr><td>16</td><td>Destination folder does not exist or is not accessible</td></tr><tr><td>17</td><td>Archive folder does not exist or is not accessible</td></tr><tr><td>18</td><td>Debug folder does not exist or is not accessible</td></tr></tbody></table>

</details>

<details>

<summary><strong>File operations &#x26; permissions (10–11, 21–22, 29)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>10</td><td>Failed to save the processed file</td></tr><tr><td>11</td><td>Error replacing images in the PDF</td></tr><tr><td>21</td><td>Insufficient file permissions for the operation</td></tr><tr><td>22</td><td>Failed to modify file permissions</td></tr><tr><td>29</td><td>Unable to delete the specified file</td></tr></tbody></table>

</details>

<details>

<summary><strong>Configuration &#x26; parameters (19–20)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>19</td><td>Invalid or incorrect command-line parameters provided</td></tr><tr><td>20</td><td>General VIESUS processing error</td></tr></tbody></table>

</details>

<details>

<summary><strong>PDF processing errors (13, 23–28)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>13</td><td>PDF library failed to initialise</td></tr><tr><td>23</td><td>Error during PDF flattening</td></tr><tr><td>24</td><td>PDF color conversion failed</td></tr><tr><td>25</td><td>PDF flattening initialisation failed</td></tr><tr><td>26</td><td>Image enhancement process failed</td></tr><tr><td>27</td><td>Failed to read image location data from PDF</td></tr><tr><td>28</td><td>No corresponding PDF found for TOX file</td></tr></tbody></table>

</details>

<details>

<summary><strong>Trigger &#x26; workflow management (30–35)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>30</td><td>Failed to rename the trigger file</td></tr><tr><td>31</td><td>Error copying folders</td></tr><tr><td>32</td><td>Failed to delete the trigger file</td></tr><tr><td>33</td><td>Unable to rename the specified folder</td></tr><tr><td>34</td><td>Failed to create the trigger file</td></tr><tr><td>35</td><td>Error during file archiving</td></tr></tbody></table>

</details>

<details>

<summary><strong>License &#x26; resource limits (36)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>36</td><td>Processing limit has been reached for the current license</td></tr></tbody></table>

</details>

<details>

<summary><strong>Cropping &#x26; region processing (37–39)</strong></summary>

<table><thead><tr><th width="170">Code</th><th>Description</th></tr></thead><tbody><tr><td>37</td><td>Invalid cropping rectangle specified</td></tr><tr><td>38</td><td>Cropping rectangle extends beyond page boundaries</td></tr><tr><td>39</td><td>Error during cropping operation</td></tr></tbody></table>

</details>

<details>

<summary><strong>Best practices</strong></summary>

1. **Log error codes.** Capture and log the specific code per failed file — error categories rely on knowing which codes you're hitting.
2. **Validate prerequisites.** Verify file permissions, paths, and license status before processing.
3. **Validate input.** Ensure PDFs are valid and not password-protected before queueing them.
4. **Monitor resources.** Check available disk space and memory continuously in production.
5. **Archive originals.** Use the archive setting to preserve source files before any destructive operation.

</details>

***

For configuration parameters, see [PDF Settings Reference](/configuration/pdf-settings.md). For the CLI, see [PDF CLI Reference](/reference/pdf-cli.md). For broader troubleshooting, see [Troubleshooting](/support/troubleshooting.md).


---

# 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/error-codes/pdf.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.