故障排查

无法连接服务器

确认地址、端口、反向代理路径和认证信息正确，并确认 Android 设备可以访问服务器。Kavita 需要 Auth Key，smanga 需要开启 OPDS；LANraragi 未启用鉴权时可以留空 API Key。

如果同时配置公网和内网地址，确认两个地址指向同一服务器和账号。保存失败时不要继续使用未经验证的地址。

书架为空或内容不完整

确认当前账号有目标媒体库权限，然后手动刷新。断网时只能看到已缓存的书架或已下载内容；缓存的元数据不代表正文已经下载。

阅读或下载失败

先在对应服务器网页端确认相同账户能够打开内容，再检查设备存储空间、目录权限和网络。smanga 的 PDF 需要完整下载，LANraragi 的 Archive 页面需要单独下载，Kavita 的部分功能还受版本和权限限制。

阅读进度冲突

其他设备或服务器修改阅读状态后，应用可能要求选择本地或服务器位置。页序变化时，视觉页码不能直接代表稳定的服务器进度；请确认内容版本后再选择。

本地库没有显示文件

确认目录仍存在且 Koharia 仍拥有 Android 授予的权限，然后下拉刷新。检查文件格式和组织方式：系列库只把根目录直接子文件夹作为系列，单文件库会递归显示支持的文件和图片目录。

如果目录被移动或权限被撤销，请在本地库设置中重新选择同一目录或其新位置，以恢复索引和自定义封面。

元数据写入或导入失败

导入和写入 sidecar 需要可写目录。若外部元数据发生变化，应用会显示冲突；选择保留本地版本或采用外部版本后再刷新。多个文件请使用导入流程，直接打开只支持单个文件。

仍未解决

在 GitHub Issues 中附上 Koharia 版本、Android 版本、问题步骤和已隐藏敏感信息的日志。