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

# Troubleshooting

When an integration in ZigiOps does not behave as expected, the Troubleshooting page gives you direct visibility into every phase of an action run: from the HTTP request sent to the source system, through data extraction and field mapping, to the final response from the target system. This page explains how to navigate and use those tools, how to interpret the data at each phase, and how to identify the most common error types.

### How do I access the Troubleshooting page?

{% stepper %}
{% step %}
Open the page

The Troubleshooting page is accessible from the main navigation of the ZigiOps web console. It is available in all deployment types: Windows, Linux, and ZigiWave-hosted Cloud.
{% endstep %}

{% step %}
Select the integration and action

1. Open the ZigiOps web console.
2. Navigate to the Troubleshooting page from the main menu.
3. Select the integration you want to investigate from the integration selector.
4. Select the specific action within that integration.
   {% endstep %}

{% step %}
Review the action run

The list of action runs for that action will appear. Select the action run you want to inspect.
{% endstep %}

{% step %}
Use the phase tabs

Use the phase tabs to review the data at each stage of the run.

**Note:** Each action run represents one complete execution cycle of the selected action. Reviewing multiple recent runs can help you identify whether an issue is intermittent or consistent.
{% endstep %}
{% endstepper %}

### What are action run phases and what does each one tell me?

An action run is the complete workflow of a single operation execution in ZigiOps. Each run is divided into phases that capture what happened at each step of the data flow. The phases are displayed as tabs when you open an action run on the Troubleshooting page.

The table below describes each phase and when it is most useful during an investigation.

| Phase        | What It Contains                                                                                                                        | When to Check It                                                                                                                                        |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status       | Execution flow summary: whether the action run succeeded or failed, and any top-level errors encountered during the run                 | First stop for every investigation. Confirms whether the run completed and surfaces the primary error if it did not.                                    |
| Extract HTTP | The full HTTP request sent to the source system and the raw HTTP response returned. Disabled by default; enable in General Settings.    | When the source system appears to be returning unexpected data, or when you suspect an authentication or connectivity issue with the source.            |
| Extract      | The extracted document: the data pulled from the source system HTTP response after being filtered through the action trigger conditions | When the wrong records are being collected, or when no records are being collected despite expected data being present in the source.                   |
| Load         | The load document: the extracted data after being transformed through the field mapping configuration                                   | When records are being collected but arriving in the target system with incorrect field values. Compares the extracted data against the mapping output. |
| Load HTTP    | The HTTP request sent to the target system and the raw HTTP response returned. Disabled by default; enable in General Settings.         | When the target system is rejecting records or returning errors. Shows the exact payload sent and the API response received.                            |
| Response     | The response document from the target system after creating or updating a record                                                        | When confirming that the target record was created or updated correctly, or when troubleshooting respond field mapping issues.                          |
| UQL          | The internal query sent against the ZigiOps schema during the action run                                                                | Advanced use. Relevant when investigating schema-level query behavior, typically with support guidance.                                                 |

**Note:** The Extract HTTP and Load HTTP phases are disabled by default to minimize data storage. To enable them, go to General Settings > Debug and toggle on Collect HTTP Data. Once enabled, the data will appear for new action runs. Previously completed runs will not be retroactively populated.

### How do I export an action run for support purposes?

{% stepper %}
{% step %}
Open the Troubleshooting page

Open the ZigiOps web console and navigate to the Troubleshooting page.
{% endstep %}

{% step %}
Select the integration, action, and run

Select the integration and action. Then select the action run you want to export.
{% endstep %}

{% step %}
Export the file

Click the **Export as File** button.
{% endstep %}

{% step %}
Save and attach the export

Save the exported file. Attach it when submitting a support request.

**Note:** Before exporting, ensure that the HTTP data and payload data collection settings are enabled in General Settings if you want those phases included in the export. If those settings were not enabled when the run occurred, that data will not be available in the export.
{% endstep %}
{% endstepper %}

### What are the common error types in ZigiOps?

ZigiOps errors fall into a small number of categories. Identifying the category quickly narrows down where to look and what to fix. The table below provides a high-level overview of each error type. Each type is covered in more detail on its dedicated troubleshooting page.

| Error Type                     | Description                                                                                         | Common Cause                                                                                       | Where to Investigate Further                                                         |
| ------------------------------ | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Authentication Failure         | ZigiOps cannot authenticate against the connected system API                                        | Expired or incorrect API token, OAuth token expiry, insufficient permissions on the API account    | Troubleshooting > Auth Failures                                                      |
| Permission Error               | The API account has authenticated successfully but lacks the rights to perform a specific operation | API account missing create, update, or read permissions on the target object type                  | Troubleshooting > Permissions Issues                                                 |
| Mapping / Transformation Error | A field mapping or transformation expression has failed to produce valid output                     | Type mismatch, invalid expression syntax, missing required source field, lookup returning no match | Troubleshooting > Mapping Issues                                                     |
| Connectivity Error             | ZigiOps cannot reach the connected system endpoint                                                  | Network issue, firewall rule, incorrect Server URL, proxy misconfiguration                         | Check the Load HTTP phase; verify system instance configuration                      |
| Validation Error               | The target system rejected the API request due to a field value failing its validation rules        | Missing required field, value outside allowed range, incorrect format for a field type             | Check the Load HTTP phase for the target system error response; review field mapping |
| Correlation Error              | ZigiOps cannot find or write the correlation key, causing incorrect create/update behavior          | Correlation field missing, not mapped, or not writable by the API account                          | Check the correlation configuration in the workflow; see Correlation page            |

**Note:** The Status phase of an action run will typically indicate which category of error occurred. Start there, then move to the relevant phase (Extract HTTP, Load HTTP, or Load) for more detail on the specific failure.

### What is a quick troubleshooting sequence to follow?

If an integration is not behaving as expected, follow this sequence to identify the cause efficiently:

{% stepper %}
{% step %}
Check the Status phase

Open the most recent failed action run and review the Status phase. It will confirm whether the run failed and provide a top-level error summary.
{% endstep %}

{% step %}
Identify the error type

Use the error type table above to match the error description to a category. This tells you which phase and which detailed troubleshooting page to consult next.
{% endstep %}

{% step %}
Check the relevant phase

For source-side issues, review the Extract and Extract HTTP phases. For target-side issues, review the Load, Load HTTP, and Response phases.
{% endstep %}

{% step %}
Compare Extract vs Load

If the data was collected correctly but arrived incorrectly at the target, the issue is in the field mapping or transformation. Compare the Extract document against the Load document to identify the discrepancy.
{% endstep %}

{% step %}
Enable HTTP data collection if needed

If the Extract and Load documents look correct but the target system is still rejecting the record, enable Collect HTTP Data in General Settings and re-trigger the run. The Load HTTP phase will show the exact API request and response.
{% endstep %}

{% step %}
Export and escalate if unresolved

If you cannot identify the cause, export the action run as a file and contact ZigiWave Support. Include the integration name, the action name, and a description of the expected versus actual behavior.
{% endstep %}
{% endstepper %}

### Where can I go from here?

The following pages provide detailed guidance on specific error types and related topics:

* [Auth Failures](#) — Step-by-step guidance for diagnosing and resolving authentication errors in ZigiOps integrations
* [Mapping Issues](#) — How to identify and fix field mapping and transformation errors
* [Permissions Issues](#) — How to diagnose and resolve API permission errors
* [Correlation](#) — Understanding and fixing correlation configuration issues that cause duplicate or missing records
* [Logs](#) — How to access and configure ZigiOps logs, including enabling HTTP and payload data collection
* [General Settings](#) — Full reference for the Debug settings that control data collection on the Troubleshooting page


---

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

```
GET https://docs.zigiwave.com/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.