Troubleshooting
How to identify and resolve common Connector errors.
Overview
If a Connector run fails, the cause is usually one of four things: credentials or permissions, an incorrect file path or pattern, a change in file structure, or an incomplete file upload. This page covers how to diagnose and fix the most common issues.
Check the Connector status
Start by going to the Connectors dashboard and reviewing the Last Status column. If a Connector shows Failed, select it to open its run history and review the error message for that run.
📸 Screenshot of the Connectors dashboard showing a failed run
Common connection errors
Invalid credentials
Cause: Credentials are incorrect, expired, or have been rotated without updating the Connector.
Check that:
Credentials are correct and have not expired
Any tokens or secrets that have been rotated are updated in the Connector settings immediately
Insufficient permissions
Cause: The storage account user or role does not have the required access.
Check that:
The account can read and write to the configured location
Access has not been restricted beyond what the Connector requires
Incorrect path or prefix
Cause: The configured location does not match the actual storage path.
Check that:
Folder and container names are correct
File paths are accurate
Casing is correct where the storage type is case-sensitive
Common file errors
File does not match file pattern
Cause: The file name does not match the pattern configured in the Connector.
Check that:
The file name matches the wildcard pattern (for example,
contacts-*.csv)The file extension is correct
Files that do not match the pattern will not be processed.
File structure has changed
Cause: Column names were added, removed, or renamed after the Connector was activated.
Check that:
The header row matches the original sample file
Column names are unchanged
All required fields are still present
If changes to the file structure are needed, update the Connector configuration before uploading the file.
Invalid data format
Cause: Data types do not match the expected format.
Common examples include incorrect date formats, unexpected boolean values, and numeric fields containing text. Review your file against the sample file used during setup and ensure consistency.
Partial or incomplete file
Cause: The file was not fully uploaded before the Connector's next scan cycle.
Check that:
The upload completes before the next five-minute scan window
The file is not being modified during processing
Import-specific issues
No data imported
If a run completes but no data was written to UbiQuity, possible reasons include:
All rows failed validation
Deduplication removed all rows
The file contained only a header row with no data
Review the success notification or run summary for row-level counts to identify where rows were dropped.
Export-specific issues
No file generated
If an Export Connector runs but produces no output file, possible reasons include:
The export filter returned no matching records
The scheduled frequency has not yet triggered
The Connector is inactive
Check the schedule configuration and confirm the Connector is active.
Preventing common issues
Most Connector failures are avoidable. To reduce the likelihood of errors:
Use consistent file naming conventions that match your configured pattern
Avoid changing file structure without updating the Connector mapping first
Rotate credentials carefully and update the Connector immediately after rotating
Use dedicated service accounts rather than personal credentials
Monitor failure notifications so issues are caught early
When to contact support
If you cannot resolve the issue, contact support and include:
Your account name
The Connector name
The run time
The error message
The file name, if applicable
The storage type (SFTP, Azure Blob Storage, or Amazon S3)
Providing these details upfront will help the support team resolve your issue faster.
Last updated
Was this helpful?