Troubleshooting
Learn how to troubleshoot ZigiOps integrations: use action run phases, interpret error types, export diagnostic data, and resolve common issues.
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?
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.
Select the integration and action
Open the ZigiOps web console.
Navigate to the Troubleshooting page from the main menu.
Select the integration you want to investigate from the integration selector.
Select the specific action within that integration.
Review the action run
The list of action runs for that action will appear. Select the action run you want to inspect.
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.
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.
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?
Open the Troubleshooting page
Open the ZigiOps web console and navigate to the Troubleshooting page.
Select the integration, action, and run
Select the integration and action. Then select the action run you want to export.
Export the file
Click the Export as File button.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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
Last updated
Was this helpful?