# Troubleshooting ### 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. --- # Agent Instructions: 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.ubiquity.co.nz/documentation/data-and-integrations/connectors/troubleshooting.md?ask= ``` 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.