Error Handling and Troubleshooting

The Davix H2I n8n node implements error handling at the item level inside execute(). Each input item is processed inside a try/catch, so failures are handled per item rather than through one global wrapper for the whole run. This is the core of the node’s troubleshooting model and explains why the node can either stop on error or continue and emit structured error output, depending on the workflow setting.

This page documents the confirmed error and troubleshooting behavior for the node:

• validation failures
• HTTP and API request failures
• backend error parsing
• continue-on-fail behavior
• common failure cases
• practical debugging based on the implemented code paths

Error handling model overview #

The node wraps per-item execution in a try/catch inside execute(). That means:

• one item can fail without necessarily invalidating later items
• error handling happens at item scope
• behavior changes depending on whether continueOnFail() is enabled

The shared request helper, davixRequest(), catches HTTP request failures and transforms them into NodeApiError. Validation and operation-level failures can also be raised as normal Error or NodeOperationError, depending on the branch and condition involved.

In practice, the error model is:

• configuration or validation failures happen before a valid request is sent
• transport and API failures happen during outbound request execution
• post-response failures happen when the response cannot support the requested output behavior, such as binary download without a URL

Continue On Fail behavior #

The node explicitly supports Continue On Fail.

When continueOnFail() is enabled:

• the node emits a JSON error object for the failed item
• the loop continues to later items
• the output item can include error, and optionally description and httpCode

When continueOnFail() is not enabled:

• the node rethrows the error
• execution stops at the failing item

That means troubleshooting in n8n should always take into account whether the workflow is configured to stop on the first error or to collect item-level error outputs instead.

Validation errors #

The documentation confirms several validation errors raised before or during request construction.

Missing Base URL #

If the Base URL is missing from credentials, the helper throws:

Missing Base URL in credentials.

Invalid Base URL #

If the Base URL is not a valid absolute URL, the helper throws:

Base URL must be a valid absolute URL.

Non-HTTPS Base URL #

If the Base URL does not use HTTPS, the helper throws:

Base URL must use HTTPS.

Embedded credentials in Base URL #

If the Base URL contains embedded credentials such as username:password@host, the helper throws:

Base URL must not include embedded credentials.

Missing API key #

If the configured credential does not provide an API key, the helper throws:

Missing API Key in credentials.

These errors should be treated as credential setup issues, not as operation-specific failures. They happen before a valid authenticated request can be completed.

[Image placeholder — n8n credential screen showing the Base URL and API Key fields used for troubleshooting credential errors]

Binary-input validation errors #

The node validates binary input fields for Image, PDF, and Tools workflows.

No binary property names provided #

If the binary property list is empty, the node throws:

No binary property names provided.

This usually means the resource-specific binary input field, such as imageBinaryProps, pdfBinaryProps, or toolsBinaryProps, is blank or resolves to an empty list.

Upload-size validation #

The node includes upload-size validation for binary uploads. When this validation is triggered, reduce the number or size of input files and refer to the shared Errors and Limits page for the current numeric limit details.

Operation-specific validation errors #

The node includes several validation rules that depend on the selected resource and operation.

Image Multitask requires selected actions #

For Image → multitask, the node throws an error if no action is selected:

Select at least one action for multitask.

Tools Single requires one selected tool #

For Tools → single, the node throws:

Select one tool for single action.

Tools Multitask requires at least one selected tool #

For Tools → multitask, the node throws a NodeOperationError if no tools are selected:

Please select at least one tool for Multitask.

These errors are node-side request-construction failures, not network failures. They should be resolved by reviewing the selected operation fields in the node UI.

PDF reorder validation #

For PDF → reorder, the node validates the order input and can throw two documented errors.

If the JSON syntax is invalid:

Invalid order JSON. Please provide a valid JSON array like [3,1,2].

If the parsed array is invalid:

Invalid order array. Use positive integers only, for example [3,1,2].

This is an operation-specific validation rule that should be debugged at the field-input level rather than at the credential or API level.

Post-response binary-download errors #

The node can optionally convert returned URLs into n8n binary output for H2I, Image, and PDF. That output behavior depends on the response containing a usable URL.

If binary download is enabled but no URL is available in the response, the node throws:

No URL returned to download.

This can affect:

• H2I when downloadBinary is enabled
• Image when imageDownloadBinary is enabled
• PDF when pdfDownloadBinary is enabled

Troubleshooting steps for this error:

• verify that the selected operation normally returns a downloadable URL
• verify that binary download is actually needed for this step
• inspect item.json without binary download to see the raw backend response
• re-enable binary download only when the response includes the expected URL output

HTTP transport and API errors #

The request helper uses this.helpers.request(...) for API calls and catches request errors inside davixRequest(). It extracts:

• HTTP status code
• error body
• backend envelope fields such as code, message, hint, and requestId when available

These failures are surfaced as NodeApiError, with message and description content built from the available error information.

Status-specific handling confirmed in code #

The documentation confirms status-specific handling for:

• 429
• 503
• 413

The repository docs do not document special branch-specific handling for:

• 400
• 401
• 403
• 404
• 500

Those other status codes may still surface through the error path, but they are not documented as having their own dedicated helper messaging.

Backend error envelope handling #

The helper parses backend error envelopes through parseDavixErrorEnvelope(). The documentation confirms that it may extract fields such as:

• error.code or top-level code
• error.message or top-level message
• hint
• requestId

This matters for troubleshooting because surfaced node errors may contain backend-originated diagnostic details, not just local node validation text. Those details can help distinguish between invalid input, rejected request content, temporary service conditions, and request-size problems.

Download failures #

The node also uses downloadToBinary() for binary-output download. That helper does not implement a local try/catch; failures from that path bubble back to the item-level handler in execute().

That means a binary-download failure is still handled under the same per-item model:

• emitted as an error item if Continue On Fail is enabled
• stops execution if Continue On Fail is disabled

Error output structure when Continue On Fail is enabled #

When the node continues on failure, it emits an output item with structured error data rather than throwing all the way out of the node. The documented JSON structure includes:

• error
• optional description
• optional httpCode

A public-facing representation is:

{
  "json": {
    "error": "<error message>",
    "description": "<optional details>",
    "httpCode": "<optional HTTP status>"
  }
}

This is the expected output contract for failed items when Continue On Fail is enabled.

Practical debugging workflow #

The source-backed observability documentation supports a practical debugging path that starts with the node’s own execution structure and request-building logic.

1. Confirm resource and operation #

Start by confirming:

• the selected Resource
• the selected Operation
• the fields that are supposed to be visible for that combination

Many failures are caused by operation-specific requirements such as missing tool selections, missing multitask actions, invalid reorder input, or enabling binary download when the response does not contain a URL.

2. Confirm credentials #

Verify:

• Base URL is present
• Base URL is valid and HTTPS
• Base URL does not contain embedded credentials
• API key is present

If the node fails before sending the request, credentials are one of the first areas to check.

3. Confirm binary input fields #

For Image, PDF, and Tools:

• make sure the resource-specific binary property field is not empty
• make sure those property names actually exist on the incoming n8n item
• make sure the current upload stays within the allowed node-side limit

4. Confirm operation-specific inputs #

Examples:

• Image Multitask needs selected actions
• Tools Single needs one selected tool
• Tools Multitask needs at least one selected tool
• PDF Reorder needs valid positive-integer order input

5. Inspect JSON before binary download #

If a failure happens during binary output handling:

• temporarily disable the download-binary toggle
• inspect the raw item.json
• verify whether the response actually contains a usable URL
• re-enable download only when the response shape supports it

[Image placeholder — node editor showing a binary download toggle used for debugging output issues]

Observability limits of the node #

The repository does not implement explicit runtime logging inside the node code. There are no documented runtime console.log statements in the node files and no node-level debug mode field in the execution flow.

In practice, troubleshooting relies on:

• n8n execution results
• item-level error output
• request validation messages
• backend error details surfaced through the helper
• comparison of node field values and input binary data

Common troubleshooting scenarios #

The node is installed, but every request fails immediately #

Check credentials first:

• Base URL
• API key
• HTTPS usage
• no embedded credentials in the URL

An Image, PDF, or Tools workflow says no binary property names were provided #

Check the relevant field:

• imageBinaryProps
• pdfBinaryProps
• toolsBinaryProps

Then verify that the incoming item actually contains binary data under those property names.

A multitask workflow fails before the request is sent #

Check that the required selection field is populated:

• Image Multitask → actions
• Tools Multitask → tools

A reorder workflow fails #

Check the order field format and use a valid positive-integer sequence when using JSON-array style input.

Binary output fails even though the request succeeded #

Disable binary download and inspect the raw JSON response first. The documented error path confirms that binary output requires a returned URL.