> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md). # Troubleshoot Product Catalog Errors & Warnings Each product catalog has a health score that indicates which, if any, problems are present in your catalog. Issues can appear at any stage: when the file is uploaded or connected, after it is processed, or when your partners try to view and promote your products. Use this guide to work through problems at each stage and get your catalog into the *excellent* range. {% hint style="info" %} **Tip:** A healthy catalog is about more than clearing errors. Follow the [Product Catalog Best Practices](/brand/what-would-you-like-to-learn-about/platform-features/product-catalogs/product-catalog-best-practices.md) to keep your data complete, well-structured, and set up for strong visibility and performance. {% endhint %} {% embed url="" %} ## Catalog health scores 1. From the left navigation menu, select ![](/files/CDnwOBeIdds9r3Z6zTnO) **\[Engage]** **→** **Content** **→** **Products** **→** [**Product Catalogs**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml). 2. If a catalog has any errors, warnings, or duplicate line items, the *Health* column shows how many of each are present. * Upload methods that automatically fetch the catalog update on their own the next time a fetch event happens.
Health descriptions | Health indicator | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Pending** | Your product catalog is awaiting its first upload or data fetch. | | **Processing** | Your product catalog is being processed. | | **Excellent** | Indicates a healthy catalog. This product data set is complete and well-structured, giving it the best chance of performing effectively. | | **Good** | Indicates that certain suggested fields containing crucial data, like category or description, could be missing. Addressing these gaps improves the overall quality of your catalog. | | **Poor** | Indicates that required information is missing in more than 10% of the records you provided. This catalog must be fixed and re-uploaded. |
## Troubleshoot upload & connection issues Before a catalog can be processed, impact.com must successfully receive it. The steps below are grouped by the upload method you selected when creating the catalog. If you are not sure which method is in use, select the catalog and review its *Upload Method* settings. ### Direct Upload Direct Upload issues are usually a format or file-name mismatch, or a file that exceeds the 1 GB limit. | Issue | What to check | How to fix it | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Wrong format selected | The format you chose (for example, TXT) does not match the file you uploaded (for example, XML). | Re-upload and select the format that matches your file. XML files use the `.xml` extension, CSV files use `.csv`, and TAB-delimited files use `.txt`. | | File name mismatch | The name of the file you uploaded must exactly match the *Upload File Name* set in your catalog settings, including the extension. | Rename your file, or update the *Upload File Name* so the two match exactly. | | Compressed file won't process | impact.com supports gzip and standard zip-compressed files. A compressed file can use a second extension to denote compression, for example `catalog.xml.gz`. | Confirm your compression type is gzip or zip, and that the file uses the correct extensions for both its format and its compression. | ### impact.com FTP server Most FTP issues come down to connection settings or credentials. | Issue | What to check | How to fix it | | --------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Can't connect to the server | Confirm you are connecting to host `products.impact.com` on port `21`. | Update your FTP client with the correct host and port, then reconnect. | | Missing FTP credentials | You need the FTP login and password issued for your account to connect. | Locate your *FTP Product Data System credentials* in your account's technical configuration settings. If you cannot find or access them, [contact support](https://app.impact.com/support/portal.ihtml). | ### Pull From URL Supported protocols for *Pull From URL* are `http://`, `https://`, `ftp://`, and `sftp://`. If your catalog isn't loading, updating, or processing correctly, use the table below to identify and resolve the issue. | Issue | What to check | How to fix it | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | URL isn't a direct download link | Open your URL in a browser. If it redirects to a login page, a cloud storage landing page, or returns a 404 or 403 error, the URL is not a direct download link. | Update the URL to one that downloads the file directly or displays it as raw data when opened in a browser. | | File name mismatch | The *Upload File Name* in your catalog settings must exactly match the actual file name at the URL, including the extension (`.csv`, `.xml`, `.txt`, `.gz`). | Update the *Upload File Name* to match your file name exactly. A small mismatch causes a *No catalog found for the request* error. | | Format or delimiter mismatch | Confirm that the format selected (CSV, TXT, XML, GMC) matches your file. If you use a delimited file, confirm the delimiter (comma, tab, pipe) matches what's configured. | Correct the format or delimiter in your catalog settings. A mismatch causes *No valid records found* errors. | | FTP/SFTP: invalid credentials or path | Verify that your URL uses the format `sftp://{username}:{password}@{host}/{file_path}`. The path must point to the exact file, not just a directory. Special characters in credentials must be URL-encoded (for example, `@` becomes `%40`). | Test your credentials with an FTP client such as FileZilla. Update the URL with corrected credentials and the full file path. | | Pull times out or fails to connect | Your server's firewall may be blocking impact.com's requests. | Contact your hosting provider or IT team to allowlist impact.com's IP address ranges. | | URL requires authentication | This upload method does not support session-based or cookie-based authentication. | Use a publicly accessible direct download URL, HTTP Basic Auth embedded in the URL (`https://user:pass@host/path`), or FTP/SFTP with credentials in the URL. If your feed requires browser-based login, switch your catalog to a different upload method, such as *Direct Upload* or the *impact.com FTP server*. | | URL exceeds 2,048 characters | Signed cloud storage URLs can exceed the 2,048-character limit and may be truncated. | Use a URL shortener that preserves the direct download, or host the file at a shorter URL. | | Catalog stuck in Processing or Pending | Check whether the file is still accessible at the URL and whether the file size is unusually large for your pull frequency. | Verify the file is available. If the catalog remains in *Processing* or *Pending*, [contact support](https://app.impact.com/support/portal.ihtml) to request a manual reprocess. | | Catalog stopped auto-updating | Check whether the file is still available at the same URL, and whether the file name, format, or server access settings have changed. | Restore the file at the original URL, or update your catalog settings to reflect the new URL or file name. For large catalogs (1,000,000+ items), consider reducing the pull frequency to avoid timeouts. | | Fields or data missing after upload | Confirm that your field names match the selected format's specification, for example [Google Merchant Center fields](https://support.google.com/merchants/answer/7052112) for GMC format. Map custom fields outside the standard specification to impact.com's custom field slots (`Numeric1`, `Text1`, and so on). | Download your uploaded catalog from impact.com and compare it to your source file to find where data is being lost. Update field names or mappings as needed, then re-upload. | ### Integrated Shopping Cart Import This method pulls your catalog from an existing e-commerce platform. Most connection problems come down to incorrect credentials or missing read permissions. Select your platform below. {% tabs %} {% tab title="Shopify" %} If you see an error such as *Unsuccessful HTTP status code when connecting to Shopify: 401* or *No valid records found in the catalog file*, your authentication details or permissions are usually the cause. * Your password must be the **Admin API access token**, which starts with `shpat_` (or `shap_`). You'll find it in your Shopify Admin under **Apps** **→** **API Credentials** **→** **Admin API access token**. * If you don't see the **Admin API access token**, select **Install app** in Shopify to generate it. * Confirm the `read_products` permission (scope) is granted to the app. Without it, Shopify returns an error stating the action requires merchant approval for the `read_products` scope. * For collections, find the collection ID in your Shopify Admin under **Products** **→** **Collections**. Select the collection; its ID appears at the end of the page URL. For full setup steps, see the [Shopify product catalog integration guide](https://integrations.impact.com/impact-brand/docs/shopify-product-catalog). {% endtab %} {% tab title="WooCommerce" %} If you see *Connection to WooCommerce was unsuccessful. Please try again*, check your credentials and API settings. * Your **API Username** is your WooCommerce *Consumer Key*, and your **API Password** is your *Consumer Secret*. * Enable the Legacy REST API in WooCommerce: **WooCommerce** **→** **Settings** **→** **Advanced** **→** **Legacy API**, then select the checkbox to enable it. For reference, see the [WooCommerce REST API documentation](https://woocommerce.com/document/woocommerce-rest-api/). {% endtab %} {% tab title="BigCommerce" %} Connecting BigCommerce requires two values and the correct read-only permissions. * Enter your **Store Hash** and **Access Token** in the impact.com UI. Your store hash is the identifier in your store's API path. * Set the **Products** and **Information & settings** permissions to read-only when you create the API account in BigCommerce. For reference, see BigCommerce's guide to [creating API tokens](https://developer.bigcommerce.com/docs/storefront-auth/tokens#create-a-token). {% endtab %} {% tab title="Shoplazza" %} Your Shoplazza private app needs read access to the following resources: `product`, `collection`, and `shop`. For setup steps, see Shoplazza's guide to [building private apps](https://www.shoplazza.dev/reference/quick-construction-of-private-apps). {% endtab %} {% endtabs %} ## Troubleshoot errors & warnings after upload Once a file is received, impact.com validates each record. Errors prevent records from being processed, while warnings flag data that was accepted but may cause problems. Use the sections below to interpret and resolve them. ### View errors & warnings 1. In the *Health* column, select the **errors**, **warnings**, or **duplicates** link. * You'll be redirected to a page with more detail. Only the first item in a set of duplicates is represented in impact.com; all items duplicating the first are ignored. 2. Optionally, use the *Search* field and filters at the top of the page to sort through the issues. 3. Review the issues and make changes as required, then re-upload your product catalog.
Filter descriptions | Filter | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | | Error Type | Filter specifically for *Errors*, *Warnings*, *Duplicates*, or *All* issues. | | Required | Filter for any specific missing required product catalog fields, or *All* fields. | | Suggested | Filter for any specific missing recommended product catalog fields, or *All* fields. | | Invalid | Filter for any specific validation-based error, such as a duplicate SKU, an invalid Google Category Code, or other errors. |
Common error & warning messages | Message | Explanation | | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *Record 'X': Required field(s) missing: (field name)* | The specified line is missing one or more required fields. | | *Record 'X': CatalogItemId(CatalogItemId): Required field(s) missing: (field name)* | A line in the data file is missing a required field. | | *No catalog found for the request. Check if the file name of uploaded file is the same as the one registered with the catalog* | The *Upload File Name* set in the *Upload Method* section when creating the catalog doesn't exactly match the name of the file you uploaded. | | *No attributes present in the catalog file* | The product catalog data file doesn't have any processable data. | | *Catalog item with ID occurs more than once in the catalog, and those after the first will be ignored* | Two or more items have the same ID. All products require a unique value, and duplicate items are not processed. | | *Record 'X' has an error: (line X) invalid char between encapsulated token and delimiter* | A line contains an invalid use of double quotes. Enclose the field in double quotes and replace all other double quotes with two double quotes. | | *(Startline X) EOF reached before encapsulated token finished* | EOF means "end of file". The start line mentioned has an opening double quote without a closing double quote, or an unexpected line break interrupted the data stream. | | *Error parsing (catalog type) field: with value: (field)* | The product field is invalid and cannot be accepted. | | *Record (recordNumber) has an error: The number of delimited values (FieldsLength) does not match the expected (ColumnNamesLength)* | For a given row, data exists in a column that has no header. | | *No valid records were found in the catalog file* | The data file is empty, the data detected isn't valid, or the file name specified is incorrect. | | *More than 10% of the records in the file had errors* | The data file cannot be processed if this occurs. See *Understand the 10% error threshold* below. | | *The processing failed because of an internal system error...* | No action is required from you. The last catalog that processed successfully continues to be available to media partners. Refer to the [impact.com status page](https://status.impact.com/) for details on service interruptions. | | *Field (field name) with value (field value) does not have a valid protocol* | The field value is not a properly formatted URL. |
### Formatting & delimiter warnings | Issue | How to fix it | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Delimiter issues: a wrong comma, tab, or empty line breaks the boundary between fields. | Correct the delimiter usage in the catalog file so each field is separated consistently, then re-upload. | | New lines in a description field break record processing. | New lines are not supported in delimited text formats (CSV and TSV). Remove line breaks from text fields such as descriptions before uploading. | ### Google Merchant Center format errors If you use the Google Merchant Center (GMC) format, most issues arise around the format's `Category` section, predefined field values, or the XML structure. {% tabs %} {% tab title="Missing Google Product Category" %} When you select *errors* on the *Product Catalogs* screen, you may see *Missing Google Product Category* in the *Suggestions* column. This means no Google Category Code or full Google category string was included in your catalog. To resolve this, refer to your [Google Merchant Center account](https://merchants.google.com/). Google automatically suggests categories for items; use these suggestions when uploading the corrected catalog.
{% endtab %} {% tab title="Google Product Category Mismatch" %} When you select *errors* on the *Product Catalogs* screen, you may see *Google Product Category Mismatch* in the *Invalid* column. This means the category used for items in your catalog does not match the expected [taxonomy code](https://www.google.com/basepages/producttype/taxonomy-with-ids.en-US.txt) (for example, 7386) or the full category format Google provides, for example: `Animals & Pet Supplies > Pet Supplies > Bird Supplies > Bird Cage Accessories > Bird Cage Food & Water Dishes` To resolve this, correct the format in which the Google Product Categories are listed, then re-upload your catalog.
{% endtab %} {% tab title="Availability value not accepted" %} An error such as *Could not parse field: availability with value* means a predefined field is using a value GMC doesn't recognize. For GMC catalogs, categories and values must be exact. * Use `availability` for the availability field. * Supported availability values are `in_stock`, `out_of_stock`, `preorder`, and `backorder`. * Check for special symbols that can affect formatting, such as a currency symbol appearing in a value field. {% endtab %} {% tab title="XML: no valid records found" %} If you upload a Google Merchant Center (XML format) catalog and see *No valid records found in the catalog file. Please fix file and re-upload*, the XML structure is likely incorrect. The XML file must contain `rss`, `RDF`, or `feed` in its starting element. Correct the root element and re-upload. {% endtab %} {% endtabs %} {% hint style="info" %} **eBay Commerce Merchant Center format:** In a `.csv` file, replace the spaces in the field column values (categories) with underscores. For example, use `Item_Title` rather than `Item Title`. {% endhint %} ### Understand the 10% error threshold If more than 10% of the records in an uploaded file contain errors, the file is not processed. When this happens: * Your catalog continues to show the version from the last successful upload, so an older *last successful submission* timestamp is expected. * The **View Products** option only appears if a file was previously uploaded successfully for that catalog ID. Fix the flagged records so fewer than 10% contain errors, then re-upload. ## Make your catalog available to partners A healthy catalog still won't reach your partners until you make it available and meet the requirements for partner visibility. Use this section if your catalog processed successfully but partners are encountering issues with visibility, product access, or tracking links. ### Partners can't see the catalog Check the following two settings: * Make sure the catalog is available for use: 1. Select ![](/files/CDnwOBeIdds9r3Z6zTnO) **\[Engage]** **→** **Content** **→** **Products** **→** [**Product Catalogs**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml) and find the catalog. 2. Select ![](/files/mQTDSmR70Q3Eybmgev6e) **\[More]** and then choose **Make Available for Use**. * Check whether partner access is restricted: 1. Select ![](/files/CDnwOBeIdds9r3Z6zTnO) **\[Engage]** **→** **Content** **→** **Products** **→** [**Product Catalogs**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml) and find the catalog. 2. Hover over the catalog, then select **Edit**. 3. In the *Restrict Partner Access* section, check whether **Allow access to only specific Partners** is ![](/files/OoA2qxPalfCYKZvmxuU6) toggled on. 4. If it is, ![](/files/5SMwTyaETie506iHU7M3) toggle it off and select **Save**. ### Partners can't see or search specific products For a product to be visible in the partner UI, it must meet all of the following requirements: * The original price is greater than $2.00 USD. * The product's Stock Availability is not *Out of Stock.* * The product has a valid product URL that leads to a live product details page. * The product has an image URL. * The product is in a catalog without [rules](/brand/what-would-you-like-to-learn-about/platform-features/product-catalogs/create-and-manage-product-catalog-rules.md) applied. ### Partner tracking links return a "malformed" error If partners see "The link you clicked on is malformed" when using tracking links from your products, deep linking is usually not enabled, or the product's landing page domain isn't set as a permitted domain. To enable deep linking, set your permitted domains, and resolve this error, see [Set Up Permitted Domains for Deep Linking](/brand/what-would-you-like-to-learn-about/account-administration/program-settings/tracking-settings/set-up-permitted-domains-for-deep-linking.md). --- # 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, and the optional `goal` query parameter: ``` GET https://help.impact.com/brand/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.