> 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/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md).

# 排查产品目录错误和警告

每个产品目录都有一个健康评分，用于显示目录中的问题。使用本指南解决 impact.com 处理目录后报告的错误和警告，以及合作伙伴可见性问题，让目录保持在 *<mark style="color:$success;">优秀</mark>* 范围内。

如果 impact.com 无法接收您的目录文件，请参阅 [排查产品目录上传和连接问题](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-uploads-and-connections.md).

{% hint style="info" %}
**提示：** 目录健康状况不仅仅是清除错误。请遵循 [产品目录最佳实践](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/product-catalog-best-practices.md) 确保数据完整、结构清晰，并经过妥善设置，以获得良好的可见性和性能。
{% endhint %}

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FZTsEfqMM8xnWruw90lbm%2Feng-350-5.mp4?alt=media&token=80c0e779-2118-482b-9a88-10ff3da3f8a4>" %}

## 目录健康评分

1. 在左侧导航菜单中，选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[Engage]** **→** **内容** **→** **产品** **→** [**产品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml).
2. 如果目录中存在错误、警告或重复的行项目， *健康状况* 列会显示各类问题的数量。

   * 自动上传方式会在下次计划抓取时更新目录。

   <div data-with-frame="true"><figure><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fwb6UpOjdauuM3qPQDscv%2FScreenshot%202026-05-08%20at%2012.11.55.png?alt=media&amp;token=02870515-9607-4c35-9672-a7797df388b2" alt="" width="563"><figcaption></figcaption></figure></div>

每个目录的 *健康状况* 列中会显示以下健康状态之一：

* *<mark style="color:$info;">待处理</mark>*: 您的产品目录正在等待首次上传或数据抓取。
* *<mark style="color:orange;">处理中</mark>*: 您的产品目录正在处理中。
* *<mark style="color:$success;">优秀</mark>*: 表示目录状况良好。此产品数据集完整且结构清晰，因此最有可能发挥出色效果。
* *<mark style="color:$warning;">良好</mark>*: 表示可能缺少某些包含重要数据的建议字段，例如类别或描述。补齐这些缺失信息可提升目录的整体质量。
* *<mark style="color:$danger;">较差</mark>*: 表示您提供的记录中有超过 10% 缺少必需信息。必须修正此目录并重新上传。

## 排查上传后的错误和警告

收到文件后，impact.com 会验证每条记录。错误会阻止记录被处理；警告则表示数据已被接受，但可能会引发问题。请参阅以下部分，了解这些问题并进行解决。

### 查看错误和警告

1. 在 *健康状况* 列中，选择 **错误**, **警告**或 **重复项** 链接。
   * 您将跳转到一个包含更多详细信息的页面。impact.com 仅保留一组重复项中的第一项；所有与第一项重复的项目都会被忽略。
2. 您也可以使用页面顶部的 *搜索* 字段和筛选器来筛选问题。
3. 检查这些问题并按需修改，然后重新上传商品目录。

使用详情页面上的以下筛选器缩小问题范围：

* *错误类型*：筛选 *错误*, *警告*, *重复项*或 *所有* 问题。
* *必填*：筛选缺失的特定必填商品目录字段，或 *所有* 字段。
* *建议*：筛选缺失的特定建议商品目录字段，或 *所有* 字段。
* *无效*：筛选特定的验证错误，例如重复的 SKU、无效的 Google 类别代码或其他错误。

### 常见错误和警告消息

在 *上传状态* 列中，或在通过 *健康状态* 列打开的详情页面上，找到目录显示的消息。根据说明解决问题。

| 消息                                                                                                                             | 说明                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Record 'X': Required field(s) missing: (field name)*                                                                          | 指定行缺少一个或多个必填字段。                                                                                                                                                                                                                                                            |
| *Record 'X': CatalogItemId(CatalogItemId): Required field(s) missing: (field name)*                                            | 数据文件中的某一行缺少必填字段。                                                                                                                                                                                                                                                           |
| *No catalog found for the request. Check if the file name of uploaded file is the same as the one registered with the catalog* | 创建目录时， *上传文件名* 在 *上传方式* 部分设置的值与您上传的文件名不完全一致。                                                                                                                                                                                                                               |
| *No attributes present in the catalog file*                                                                                    | 商品目录数据文件中没有可处理的数据。                                                                                                                                                                                                                                                         |
| *Catalog item with ID occurs more than once in the catalog, and those after the first will be ignored*                         | 两个或更多商品具有相同的 ID。所有商品都必须具有唯一的 ID，重复商品不会被处理。                                                                                                                                                                                                                                 |
| *Record 'X' has an error: (line X) invalid char between encapsulated token and delimiter*                                      | 某一行中的双引号使用无效。请用双引号将字段括起来，并将其他所有双引号替换为两个双引号。Google Merchant Center（TXT 格式）目录接受未经转义的双引号，例如 `18"` 在商品标题中使用的双引号。                                                                                                                                                               |
| *(Startline X) EOF reached before encapsulated token finished*                                                                 | EOF 表示“文件结束”。所述起始行有一个起始双引号，但缺少结束双引号，或者意外的换行中断了数据流。                                                                                                                                                                                                                         |
| *解析（目录类型）字段时出错：值为（字段）*                                                                                                         | 产品字段无效，无法接受。                                                                                                                                                                                                                                                               |
| *记录（recordNumber）存在错误：分隔值的数量（FieldsLength）与预期数量（ColumnNamesLength）不匹配*                                                         | 某一行的数据位于没有标题的列中。                                                                                                                                                                                                                                                           |
| *在目录文件中未找到有效记录。请检查文件内容是否符合您配置的目录格式，然后重新上传。*                                                                                    | impact.com 已读取该文件，但文件中不包含任何产品记录。请检查文件是否包含您的产品且符合所选目录格式，然后重新上传。                                                                                                                                                                                                             |
| *文件中超过 10% 的记录存在错误，因此目录未更新。请检查并更正这些记录，然后重新上传文件。*                                                                               | 存在错误的记录过多，无法更新目录。这也包括所有记录均有错误的文件。请参阅 [*了解 10% 错误阈值*](#understand-the-10-error-threshold) 下文。                                                                                                                                                                               |
| *目录文件不是有效的 XML，无法读取。请确保文件格式正确、符合 XML 规范，然后重新上传。*                                                                               | XML 文件为空、内容被截断或存在未闭合标签，因此 impact.com 无法读取。请修正 XML，确保其格式正确，然后重新上传。                                                                                                                                                                                                          |
| *该文件似乎不是有效的 RSS 或 Atom 订阅源格式。请检查文件是否符合您配置的目录格式，然后重新上传。*                                                                        | 该文件不是 RSS 或 Atom 订阅源，例如，保存的可能是错误网页，而非您的订阅源。XML 目录文件的起始元素必须包含 `rss`, `RDF`或 `feed` 。                                                                                                                                                                                        |
| *我们无法读取目录文件的内容……*                                                                                                              | impact.com 无法读取文件内容。常见原因包括文件为空、文件结构异常、分隔符无效或字符编码不正确。请检查文件是否符合所选目录格式，然后重新上传。如果问题仍然存在，请 [联系支持团队](https://app.impact.com/support/portal.ihtml).                                                                                                                               |
| *我们无法从配置的拉取 URL 获取目录文件。请验证 URL 是否正确，以及文件是否可以访问。*                                                                               | impact.com 无法从您目录设置中的 *拉取 URL* 下载文件。请参阅 [*从 URL 拉取*](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-uploads-and-connections.md#pull-from-url-recommended) 《排查产品目录上传和连接问题》，了解如何排查 URL。 |
| *由于内部系统错误，处理失败……*                                                                                                              | 您无需采取任何操作。最近一次成功处理的目录仍可供合作伙伴使用。有关服务中断的详情，请参阅 [impact.com 状态页](https://status.impact.com/) 。                                                                                                                                                                                |
| *字段（字段名称）的值（字段值）不包含有效协议*                                                                                                       | 字段值不是格式正确的 URL。                                                                                                                                                                                                                                                            |

### 格式和分隔符警告

在分隔符文件（CSV 和 TSV）中，分隔符或换行符位置不当可能会错误拆分数据，导致记录无法正确处理。请使用下表解决这些警告。

| 问题                             | 解决方法                                                                                    |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| 分隔符问题：逗号、制表符使用错误或空行会破坏字段之间的边界。 | 更正目录文件中的分隔符用法，确保各字段的分隔方式一致，然后重新上传。对于 Google Merchant Center（TXT 格式）目录，impact.com 会跳过空行。 |
| 描述字段中的换行符会导致记录处理失败。            | 分隔符文本格式（CSV 和 TSV）不支持换行符。上传前，请从描述等文本字段中移除换行符。                                           |

{% hint style="info" %}
**eBay Commerce Merchant Center 格式：** 在 `.csv` 文件中，将字段列值（类别）中的空格替换为下划线。例如，使用 `Item_Title` 而不是 `Item Title`.
{% endhint %}

### Google Merchant Center 格式错误

如果您使用 Google Merchant Center (GMC) 格式，大多数问题都出在该格式的 `Category` 部分、预定义字段值或 XML 结构上。

#### 缺少 Google 商品类别

在 *错误* 屏幕上选择 *商品目录* 后，您可能会在 *缺少 Google 商品类别* 的 *建议* 列中看到此提示。这意味着您的目录中未包含 Google 类别代码或完整的 Google 类别字符串。

要解决此问题，请参阅您的 [Google Merchant Center 账号](https://merchants.google.com/)。Google 会自动为商品推荐类别；上传修正后的目录时，请使用这些推荐类别。

<div data-with-frame="true"><figure><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-c92f932de0c30c466560ef0f2b9c13a8f48100a2%2Fb61fc4733fe334479ac8dcd599a078e24be5c384633e0414cb57ba3ae9350ed3.png?alt=media" alt="" width="413"><figcaption></figcaption></figure></div>

#### Google 商品类别不匹配

在 *错误* 屏幕上选择 *商品目录* 后，您可能会在 *Google 商品类别不匹配* 的 *无效* 列中看到此提示。这意味着目录中商品使用的类别与预期的 [分类代码](https://www.google.com/basepages/producttype/taxonomy-with-ids.en-US.txt) 不匹配（例如，7386），也不符合 Google 提供的完整类别格式，例如：

`Animals & Pet Supplies > Pet Supplies > Bird Supplies > Bird Cage Accessories > Bird Cage Food & Water Dishes`

要解决此问题，请更正 Google 商品类别的列出格式，然后重新上传目录。

<div data-with-frame="true"><figure><img src="https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-a49a1b97a47722c72fe9bbb76fd2e902c1ca39ae%2F629fe5a5a308cd2ed6bd628db9c9c22547490d92bb19d1011d1657669d9b6296.png?alt=media" alt=""><figcaption></figcaption></figure></div>

#### 不接受此可用性值

类似 *无法解析字段：availability，值为* 的错误意味着预定义字段使用了 GMC 无法识别的值。

* 可用性字段请使用 `availability` 。
* 请使用以下受支持的可用性值之一： `in_stock`, `out_of_stock`, `preorder`或 `backorder`。impact.com 也接受以下变体，并会将其转换为受支持的值。
* 请检查是否存在可能影响格式的特殊符号，例如值字段中出现货币符号。货币代码不区分大小写，因此 impact.com 会将 `19.99 usd` 读取为 `19.99 USD`.

| 受支持的值          | 也接受                          |
| -------------- | ---------------------------- |
| `in_stock`     | `In Stock`, `InStock`        |
| `out_of_stock` | `Out Of Stock`, `OutOfStock` |
| `preorder`     | `PreOrder`                   |
| `backorder`    | `BackOrder`                  |

#### XML 结构错误

如果您上传 Google Merchant Center 目录（XML 格式）后看到以下提示： *The file does not appear to be a valid RSS or Atom feed format*，则 XML 结构可能不正确。

XML 文件的起始元素必须包含 `rss`, `RDF`或 `feed` 。请修正根元素并重新上传。

如果您看到 *The catalog file is not valid XML and could not be read*，则文件可能为空、被截断或存在未闭合的标签。请修复 XML，使其格式正确，然后重新上传。

### 了解 10% 错误阈值

如果上传文件中超过 10% 的记录包含错误，系统将不会处理该文件。发生这种情况时：

* 您的目录仍会显示上次成功上传的版本，因此 *上次成功提交* 的时间戳较早是正常的。
* “ **查看产品** ”选项仅在该目录 ID 之前成功上传过文件时才会显示。

请修复标记出的记录，使包含错误的记录少于 10%，然后重新上传。

## 排查合作伙伴可见性和跟踪链接问题

即使目录状态正常，您也必须 [将其设为可用](#partners-cant-see-the-catalog) 并满足 [合作伙伴可见性要求](#partners-cant-see-or-search-specific-products)，合作伙伴才能看到该目录。如果您的目录已成功处理，但合作伙伴遇到可见性、产品访问或跟踪链接问题，请参阅本节。

### 合作伙伴无法看到目录

请检查以下两项设置：

* 确保目录可供使用：
  1. 选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **【互动】** **→** **内容** **→** **产品** **→** [**产品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml) ，然后找到该目录。
  2. 选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FaMIlbqH54V4Ow5JvT0I0%2F%5BMore%5D%20vNext%202.svg?alt=media\&token=6d5449e8-e413-48fa-b059-58ebb3e2c271) **【更多】** 然后选择 **设为可用**.
* 检查是否限制了合作伙伴访问：
  1. 选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **【互动】** **→** **内容** **→** **产品** **→** [**产品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml) ，然后找到该目录。
  2. 将鼠标悬停在商品目录上，然后选择 **编辑**.
  3. 在 *限制合作伙伴访问* 部分中，检查是否已 **仅允许特定合作伙伴访问** 切换 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FiZjM1xY8o3v1iR3Zaysd%2FToggle.svg?alt=media\&token=b1550d48-bba9-4e81-8604-bc12370c5caa) 为开启状态。
  4. 如果已开启， ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FACIoqj1Ayhx8QzL9aqYB%2Ftoggle-off-solid%20\(1\).svg?alt=media\&token=a85366cd-4b70-41a6-83df-319f89597ede) 请将其关闭，然后选择 **保存**.

{% hint style="success" %}
**注意：** 只有 **设为可用** 选项仅适用于状态为 *优秀* 或 *良好* 且处于 *未激活* 或 *待激活*.
{% endhint %}

### 合作伙伴无法查看或搜索特定商品

商品必须满足以下所有要求，才能在合作伙伴界面中显示：

* 原价高于 2.00 美元。
* 商品的库存状态不是 *缺货。*
* 商品具有有效的商品网址，可跳转到正常运行的商品详情页。
* 商品具有图片网址。
* 商品所在的商品目录未应用 [规则](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/create-and-manage-product-catalog-rules.md) 。

### 合作伙伴跟踪链接返回“格式错误”

如果合作伙伴使用商品跟踪链接时看到“您点击的链接格式错误”，通常是因为未启用深度链接，或商品落地页的域名未设为许可域名。若要启用深度链接、设置许可域名并解决此错误，请参阅 [为深度链接设置许可域名](https://help.impact.com/brand/zh/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
