> 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).

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

每个产品目录都有一个健康评分，用于指出目录中存在哪些问题（如果有的话）。要让你的目录达到 *优秀* 范围，你必须排查并修正其中存在的任何错误、警告和重复项。

{% 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. 从左侧导航菜单中选择 ![](/files/209022bdb234289211a24a980f6227a8684cc439) **\[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="/files/8855092c100d76565e3a29df8f6e2ef9bd983c2a" alt="" width="563"><figcaption></figcaption></figure></div>

   * 自动拉取目录的上传方式应在下一次拉取事件发生时自动更新。

<details>

<summary>健康说明</summary>

| 健康指标    | 说明                                          |
| ------- | ------------------------------------------- |
| **待处理** | 你的产品目录正在上传。                                 |
| **处理中** | 你的产品目录正在处理中。                                |
| **优秀**  | 表示目录健康——此产品数据集完整且结构良好，因此最有可能表现出色。           |
| **良好**  | 表示某些包含类别或状态等关键信息的建议字段可能缺失。解决这些缺口将提升目录的整体质量。 |
| **较差**  | 表示你提交的记录中有超过 10% 缺少必需信息。该目录必须修复后重新上传。       |

</details>

#### 查看错误和警告

1. 在 *健康* 列中，选择 **错误**, **警告**，或 **重复项** 链接。
   * 你将被重定向到一个包含有关错误或警告更多详细信息的页面。重复项集合中只有第一条会在 impact.com 中显示；所有与第一条重复的项都将被忽略。
2. 如有需要，可使用 *搜索* 字段以及页面顶部的筛选器来对这些问题进行排序和筛选。

<details>

<summary>筛选说明</summary>

|          |                                                             |
| -------- | ----------------------------------------------------------- |
| **错误类型** | 你可以专门筛选 *错误*, *警告*, *重复项*，或 *全部* 问题。                        |
| **必需**   | 你可以筛选任何特定缺失的必需产品目录字段或 *全部* 字段。                              |
| **建议**   | 你可以筛选任何特定缺失的推荐产品目录字段或 *全部* 字段。                              |
| **无效**   | 你可以筛选任何基于验证的特定错误。这可能是重复 SKU、无效的 Google Category Code，或其他错误。 |

</details>

3. 查看这些问题并按要求进行更改。然后，重新上传你的产品目录。

<details>

<summary>常见错误和警告消息</summary>

| 错误消息                                                                                                 | 说明                                                                                                     |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| *记录“X”：缺少必需字段：(字段名)*                                                                                 | 指定的条目缺少一个或多个必需字段。                                                                                      |
| *记录“X”：CatalogItemId(CatalogItemId)：缺少必需字段：(字段名)*                                                    | 数据文件中的某一行缺少必需字段。                                                                                       |
| *请求未找到目录。请检查上传文件的文件名是否与目录中注册的文件名相同*                                                                  | 该 *上传文件名* 设置于 *上传方式* 在创建产品目录时，上传方式部分中设置的名称与您上传的文件名并不完全一致。                                              |
| *目录文件中没有任何属性*                                                                                        | 产品目录数据文件没有任何可处理的数据。                                                                                    |
| *目录中某个具有 ID 的目录项出现多次，第一条之后的条目将被忽略*                                                                   | 有 2 个或更多项目使用相同的 ID——所有产品都需要唯一值。重复项目将不会被处理。                                                             |
| *记录“X”有错误：(第 X 行) 封装标记与分隔符之间存在无效字符*                                                                  | 数据文件中的某一行对双引号的使用无效。应通过将该字段用双引号括起，并将所有其他双引号替换为 2 个双引号来正确处理（例如， *3" 软盘* 变为 *"3"" 软盘"*).                  |
| *（起始行 X）在封装标记完成之前已到达 EOF*                                                                            | <p>EOF 表示“文件末尾”。所提到的起始行包含一个开头双引号，但没有对应的结束双引号。即使读取到文件末尾，仍未找到结束双引号，因此发生了此错误。</p><p>或者，意外的换行可能中断了数据流。</p> |
| *解析（目录类型）字段时出错：值为：（字段）*                                                                              | 产品字段无效，无法接受。                                                                                           |
| *记录（recordNumber）有错误：分隔值的数量（FieldsLength）与预期数量（ColumnNamesLength）不匹配*                                | 对于某一行数据，如果某一列中存在数据但没有标题，就会发生此错误。                                                                       |
| *在目录文件中未找到有效记录*                                                                                      | 要么数据文件为空（即没有数据），要么检测到的数据无效，要么文件名指定错误。                                                                  |
| *文件中超过 10% 的记录存在错误。*                                                                                 | 如果发生此错误，数据文件将无法处理。                                                                                     |
| *由于内部系统错误，处理失败。用户无需采取任何操作。我们的工程团队已收到通知，并正在着手解决此问题。最后一个成功处理的目录将继续向媒体合作伙伴提供。如需更多信息，请联系 impact.com 支持。* | 请参阅 [impact.com 状态页面](https://status.impact.com/) 以了解服务中断详情。                                           |
| *字段（字段名）和值（字段值）没有有效的协议*                                                                              | 字段值不是格式正确的 URL。                                                                                        |

</details>

#### Google Merchant 格式错误

如果你将 Google Merchant Center 格式用作产品目录分类法，可能会遇到 2 个问题，这些问题很可能出现在该格式的 `类别` 部分。

{% tabs %}
{% tab title="缺少 Google 产品类别" %}
当你选择 *错误* 在 *产品目录* 屏幕上，你可能会看到 *缺少 Google 产品类别* 在 *建议* 列中。

这意味着你的目录中未包含 Google Category Code 或完整的 Google Category String。

要解决此问题，请参考你的 Google Merchant Center 账户。Google 会自动为条目建议类别——在上传修正后的目录时应使用此建议。

<div data-with-frame="true"><figure><img src="/files/a4fcbb83ed86088df351fae86d5cf06c7498d71a" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Google 产品类别不匹配" %}
当你选择 *错误* 在 *产品目录* 屏幕上，你可能会看到 *Google 产品类别不匹配* 在 *无效* 列中。

这意味着你目录中条目使用的类别与预期的 [分类法代码](https://www.google.com/basepages/producttype/taxonomy-with-ids.en-US.txt) （例如，7386）或 Google 提供的完整类别格式不匹配。请参见下方完整 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="/files/2000eec488450ef0d0f6f385bf96dcc2d709402c" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

#### 故障排查 *从 URL 拉取* 问题

如果你的目录配置为从 URL 拉取，但无法正常加载、更新或处理，请使用下表识别并解决问题。

<table><thead><tr><th width="230.53125">问题</th><th width="258">检查内容</th><th>修复方法</th></tr></thead><tbody><tr><td><em>URL 不是直接下载链接</em></td><td>在浏览器中打开你的 URL。如果它重定向到登录页面、云存储落地页，或返回 404/403 错误，则该 URL 不是直接下载链接。</td><td>将 URL 更新为可直接下载文件的链接，或者在浏览器中打开时直接显示原始数据。</td></tr><tr><td><em>文件名不匹配</em></td><td>该 <em>上传文件名</em> 在你的目录设置中必须与 URL 处的实际文件名完全匹配，包括扩展名（<code>.csv</code>, <code>.xml</code>, <code>.txt</code>, <code>.gz</code>).</td><td>将你的目录设置中的 <em>上传文件名</em> 更新为与你的文件名完全匹配——哪怕很小的不一致也会导致 <em>未找到请求对应的目录</em> 错误。</td></tr><tr><td><em>格式或分隔符不匹配</em></td><td>确认所选格式（CSV、TXT、XML、GMC）与你的文件一致。如果使用分隔文件，请确认分隔符（逗号、制表符、竖线）与配置一致。</td><td>在你的目录设置中更正格式或分隔符。不匹配会导致 <em>未找到有效记录</em> 错误。</td></tr><tr><td><em>FTP/SFTP：凭据或路径无效</em></td><td>请验证你的 URL 使用以下格式： <code>sftp://{username}:{password}@{host}/{file_path}</code>。路径必须指向确切的文件，而不只是目录。凭据中的特殊字符必须进行 URL 编码（例如， <code>@</code> → <code>%40</code>).</td><td>使用 FileZilla 等 FTP 客户端测试你的凭据。使用修正后的凭据和完整文件路径更新 URL。</td></tr><tr><td><em>拉取超时或连接失败</em></td><td>你的服务器防火墙可能正在阻止 impact.com 的请求。</td><td>请联系你的主机提供商或 IT 团队，将 impact.com 的 IP 地址范围加入白名单。</td></tr><tr><td><em>URL 需要身份验证</em></td><td>从 URL 拉取不支持基于会话或基于 Cookie 的身份验证。</td><td>请改用以下其中一种方式：可公开访问的直接下载 URL、在 URL 中嵌入 HTTP Basic Auth（<code>https://user:pass@host/path</code>），或在 URL 中包含凭据的 FTP/SFTP。如果你的数据源需要基于浏览器登录，请改用 <em>直接上传</em> 或 <em>FTP 推送</em>.</td></tr><tr><td><em>URL 超过 2,048 个字符</em></td><td>已签名的云存储 URL 可能会超过 2,048 字符限制，并且可能被截断。</td><td>请使用可保留直接下载的短链接工具，或将文件托管在更短的 URL 上。</td></tr><tr><td><em>目录卡在处理中或待处理状态</em></td><td>检查该文件在 URL 上是否仍可访问，以及文件大小对于你的拉取频率是否异常偏大。</td><td>验证文件可用。如果目录仍处于 <em>处理中</em> 或 <em>待处理</em>, <a href="https://app.impact.com/support/portal.ihtml?createTicket=true">请联系支持</a> 以请求手动重新处理。</td></tr><tr><td><em>目录停止自动更新</em></td><td>检查该文件是否仍可通过相同 URL 访问，以及文件名、格式或服务器访问设置是否已更改。</td><td>将文件恢复到原始 URL，或更新目录设置以反映新的 URL 或文件名。对于大型目录（100 万+ 条目），可考虑降低拉取频率以避免超时。</td></tr><tr><td><em>上传后字段或数据缺失</em></td><td>确认你的字段名与所选格式的规范一致——例如， <a href="https://support.google.com/merchants/answer/7052112">Google Merchant Center 字段</a> 适用于 GMC 格式。将标准规范之外的自定义字段映射到 impact.com 的自定义字段槽位（<code>数值1</code>, <code>文本1</code>等）。</td><td>从 impact.com 下载你上传的目录，并将其与你的源文件进行比较，以找出数据丢失的位置。根据需要更新字段名或映射，然后重新上传。</td></tr></tbody></table>


---

# 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/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md?ask=<question>&goal=<endgoal>
```

`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.