扣子知识库上传失败，最容易让人误判成“文件坏了”，但公开 issue 里更常见的情况是：解析、embedding、存储这三层里的某一层没对齐。你会看到的报错可能是 num_rows 不一致、column size not match、batch size is invalid，也可能是加载 knowledge 失败、图片解析失败、PDF 只处理到一半。
Coze（扣子）Studio 官方开源仓库是 https://github.com/coze-dev/coze-studio。官方 README 里把知识库、图片上传、模型配置都放在基础组件和开发指南里，意思其实很明确：知识库不是单独跑的，它依赖解析器、embedding 和底层向量库一起正常工作。
先别急着重传文件，先分清是哪一层在报错
如果报错发生在文档切分或解析阶段，通常是 PDF、Word、CSV、图片这类输入源有问题，或者 OCR / 解析服务没接好。如果报错发生在向量化阶段，常见原因是 embedding 配置、维度、批量大小不统一。到了存储阶段再报错，往往就是向量库写入参数不匹配。
社区里最常见的几类情况
- Excel、CSV、Word 上传后失败，最后发现是解析后的行列结构和存储预期不一致。
- 图片知识库失败，通常先看 OCR 或图像解析服务有没有正常返回。
- PDF 看起来上传了，但后面没继续，常常要去看解析和切分步骤是不是中断了。
最实用的排查顺序
先用最简单的单文件测试，不要一次传一堆。再看 embedding 维度和批量大小是否和你配置的模型一致。公开 issue 里就有人遇到过 batch size 不能大于 10 的限制，也有人遇到向量维度和 collection 定义不一致的情况。最后再看文件类型本身是不是需要 OCR、版面分析或专门的解析组件。
如果你只是反复换文件，却没看错误层级，往往会一直兜圈子。知识库问题最怕“感觉像文件问题”，实际上却是配置问题。
一句话结论
扣子知识库上传失败，先别先换文件，先分清是解析、embedding 还是存储出了问题。把报错层级看明白，定位会快很多。
