仓颉语言关系型数据库（RDB）错误码全解析：从 14800000 到 14801002 的排查实战指南

文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载本篇技术指南以 OpenHarmony 仓颉侧 ArkData 关系型数据库relational_store模块的专用错误码为主线系统梳理 29 个错误码的错误信息、触发场景、可能原因与处理步骤并结合 关系型数据库 API 文档 与 数据持久化开发指南 中的接口异常表、StoreConfig 配置项与 ResultSet 结果集语义给出可落地的排查思路。读完本文你将能够根据BusinessException.code快速定位 RDB 操作失败的根因并掌握 SQLite 底层错误14800021~14800034与SQLITE_*原生错误之间的对应关系。错误码体系概述关系型数据库错误码是 ArkData 模块下ohos.data.relational_store仓颉侧引入方式为import kit.ArkData.*特有的错误码集合编号范围为14800000~14801002。它与同属 ArkData 的分布式键值数据库错误码151xxxxx和用户首选项错误码155xxxxx相互独立。说明本模块错误码只覆盖关系型数据库自身的问题权限、参数校验、能力不支持等通用问题如错误码 801Capability not supported.由通用错误码说明文档统一说明。在仓颉 API 中RDB 相关接口的异常统一以BusinessException抛出其code字段即错误码message字段为错误信息。开发指南中给出的标准捕获写法如下import ohos.business_exception.BusinessException import kit.PerformanceAnalysisKit.Hilog try { // 增、删、改、查等数据库操作 } catch (e: BusinessException) { Hilog.error(0, ErrorCode: ${e.code}, e.message) }以getRdbStore(context, config)为例接口文档明确列出了该接口可能抛出的错误码14800000、14800010、14800011、14801001、14801002、14800017、14800020、14800021~14800023、14800027~14800030。也就是说同一个错误码会出现在多个接口的异常表中排查时应结合当前调用的是哪个接口与错误码类型双重定位。错误码速查总表错误码错误信息类别14800000Inner error.内部错误14800010Invalid database path.路径/文件14800011Database corrupted.路径/文件14800012Row out of bounds.结果集14800013Column out of bounds.结果集14800014Already closed.结果集/对象状态14800015The database does not respond.数据库状态14800016The database is already attached.数据库状态14800017Config changed.配置14800018No data meets the condition.查询14800019The SQL must be a query statement.查询14800021SQLite: Generic error.SQLite 底层14800022SQLite: Callback routine requested an abort.SQLite 底层14800023SQLite: Access permission denied.SQLite 底层14800024SQLite: The database file is locked.SQLite 底层14800025SQLite: A table in the database is locked.SQLite 底层14800026SQLite: The database is out of memory.SQLite 底层14800027SQLite: Attempt to write a readonly database.SQLite 底层14800028SQLite: Some kind of disk I/O error occurred.SQLite 底层14800029SQLite: The database is full.SQLite 底层14800030SQLite: Unable to open the database file.SQLite 底层14800031SQLite: TEXT or BLOB exceeds size limit.SQLite 底层14800032SQLite: Abort due to constraint violation.SQLite 底层14800033SQLite: Data type mismatch.SQLite 底层14800034SQLite: Library used incorrectly.SQLite 底层14800047The WAL file size exceeds the default limit.WAL/事务14800050Failed to obtain subscription service.订阅服务14801001Only supported in stage mode.模型/上下文14801002The data group id is not valid.配置14800051The type of the distributed table does not match.分布式内部错误与配置类错误14800000 内部错误Inner error.该错误是关系型数据库模块的兜底错误码表示发生了无法归入其他错误码的内部异常。文档给出的可能原因包括四类SQL 执行异常内部状态异常错误地使用接口系统级错误空指针、内存不足、数据服务异常重启、I/O 错误、IPC 异常、JS 引擎异常等。处理步骤优先查看错误日志定位具体原因然后依次排查——① 检查 SQL 语句与谓词RdbPredicates是否正确② 排查是否存在对象关闭后再使用的情况③ 确认是否严格按接口文档使用接口④ 尝试重试仍无法解决时提示用户重启应用、升级应用或升级设备版本。该错误码覆盖面极广在 cj-apis-relational_store.md 中getRdbStore、deleteRdbStore、backup、insert、update、delete、query等几乎所有接口的异常表第一行都是它。因此遇到 14800000 时务必先结合日志判断到底是 SQL、对象生命周期还是系统资源问题避免盲目重试。14800017 关键配置已被更改Config changed.数据库的area区域、isEncrypt加密、securityLevel安全级别等关键配置在数据库创建后发生了变化时触发。这些配置正是StoreConfig中在开库时固化下来的属性StoreConfig 构造函数的参数表显示securityLevel必填、encrypt默认 false、customDir默认 、dataGroupId默认 等一旦与既有数据库文件的实际配置不一致就会触发此类错误。getRdbStore的异常表也列出了 14800017。处理步骤保持原配置不变或者用原配置导出数据、删除旧库、用新配置创建新库并将数据写入新库。特别注意encrypt参数API 文档明确强调数据库创建后禁止对该参数进行修改。14801001 上下文环境非 Stage 模型Only supported in stage mode.当前上下文环境不是 Stage 模型时触发。该操作仅支持 Stage 模型。处理步骤切换当前上下文环境改用 Stage 模型开发。这与 OpenHarmony 应用模型演进方向一致getRdbStore、deleteRdbStore等接口均要求传入UIAbilityContext本身就是 Stage 模型下的上下文类型。14801002 dataGroupId 参数非法The data group id is not valid.传入的dataGroupId不是从应用市场正常申请得到的。处理步骤从应用市场申请dataGroupId并正确传入该参数。结合 StoreConfig.dataGroupId 字段说明该参数表示应用组 ID不填时默认在本应用沙箱目录下创建 RdbStore 实例同时需要注意dataGroupId 共享沙箱方式不支持多进程访问加密数据库。数据库路径与文件类错误14800010 数据库路径不合法Invalid database path.传入的数据库路径无效常见于getRdbStore、deleteRdbStore等开库/删库操作。处理步骤检查传入的数据库路径。可重点核对 StoreConfig.customDir 与 StoreConfig.rootDir 的取值约束customDir数据库路径大小限制为128 字节超过会开库失败并返回错误未配置rootDir时数据库在context.databaseDir /rdb/ customDir下创建同时配置rootDir时将从rootDir / customDir / name打开或删除数据库且此时数据库以只读模式打开必须确保对应路径下文件存在且有读取权限否则返回 14800010。14800011 数据库文件损坏Database corrupted.调用数据库增、删、查、数据同步等接口操作数据库时发现数据库文件已损坏。getRdbStore的异常表中 14800011 的完整信息为Failed to open the database because it is corrupted.。处理步骤如果之前备份过数据库可尝试使用已备份的数据库文件恢复数据库如果之前没有备份过数据库可尝试删除数据库后重新创建。数据持久化开发指南对 14800011 有专门提示关系型数据库在操作或存储过程中可能由于各种原因发生非预期异常抛出14800011。此时需要对数据库进行重建并恢复数据以保障正常的应用开发。这与StoreConfig.allowRebuild参数默认 false即异常时不自动删除重建配合使用若将该参数置为 true则数据库异常时会被自动删除并重建一个空库空表。备份与恢复的具体操作参见关系型数据库备份与恢复其中backup(Backup.db)与restore(Backup.db)分别用于手动备份与恢复。14800030 SQLite无法打开数据库文件SQLite: Unable to open the database file.SQLite 无法打开数据库文件可能原因文件不存在且创建新数据库失败文件存在但数据库文件损坏文件权限问题SQLite 无法读写文件磁盘空间不足。处理步骤① 确认数据库文件路径是否正确、检查文件权限确保应用有足够权限读写文件② 确认磁盘空间足够。结果集与列访问类错误此类错误与ResultSet结果集的操作密切相关。ResultSet是调用query/querySql等查询接口后返回的结果集合其游标默认指向第 -1 个记录有效数据从 0 开始。14800012 结果集为空或指定位置不合法Row out of bounds.可能原因结果集为空或结果集指定行号超出位置范围[0, m - 1]其中m resultsetV9.rowCount。处理步骤检查当前操作得到的结果集是否为空或指定的位置是否合法。对应ResultSet的行定位 APIrowCount结果集总行数、rowIndex当前行索引、goTo(row)、goToFirstRow()、goToLastRow()等调用这些方法前应先确认行号落在有效范围内。14800013 列值为空或列类型与当前调用接口不兼容Column out of bounds.可能原因结果集为空结果集当前行号超出范围[0, m - 1]m resultsetV9.rowCount当前列号超出范围[0, n - 1]n resultsetV9.columnCount当前列数据类型接口不支持。处理步骤① 检查结果集是否为空② 检查结果集当前行号、列号是否超出范围③ 检查当前列数据类型是否支持。仓颉侧 RDB 支持的基本数据类型为 Int64、Float64、String、二进制类型数据、Bool对应的读取接口有getLong(index)、getDouble(index)、getString(index)、getBlob(index)等取列名/列索引时可用getColumnIndex(name)、getColumnName(index)判断列是否为 null 可用isColumnNull(index)。若列中存储的类型与所选读取接口不匹配就会触发该错误。14800014 数据库或结果集关闭Already closed.可能原因RdbStore或ResultSet等带有 close 接口的对象已经调用过 close或者没有打开成功。处理步骤重新打开 RdbStore或重新查询获取 ResultSet。开发指南明确建议应用完成查询、不再使用结果集时及时调用resultSet.close()释放系统为其分配的内存。同时注意ResultSet实例不会实时刷新——使用结果集期间若数据库数据发生变化需要重新查询才能拿到最新数据。getRdbStore、backup等接口的异常表均包含 14800014。数据库状态与查询类错误14800015 数据库没有响应The database does not respond.可能原因有读、写、attach、detach 等操作正在执行无法在指定时间默认 2 秒内完成当前操作。处理步骤重新尝试。backup的异常表中也包含该错误码说明耗时较长的备份操作同样可能撞上这个超时限制。14800016 数据库别名已被使用The database is already attached.可能原因附加后的数据库别名已被使用。处理步骤不进行附加数据库操作或者修改附加后数据库的别名。14800018 查询结果没有数据符合条件No data meets the condition.可能原因SQL 语句有误未查询到符合条件的数据。处理步骤编写正确的查询语句或先向数据库添加数据后再查询。该错误是业务性错误而非系统性错误应先确认表结构与数据内容再核对谓词条件。14800019 SQL 必须是查询语句The SQL must be a query statement.可能原因调用查询类接口时传入的 SQL 语句不符合规约导致查询失败。处理步骤编写满足规约的 SQL 语句。注意查询接口如querySql要求 SQL 必须是 SELECT 类查询语句不能传入 INSERT/UPDATE/DELETE 等非查询语句。14800047 WAL 文件大小超过默认上限The WAL file size exceeds the default limit.可能原因在开启读事务或结果集未关闭的情况下不断执行增删改操作导致 WALWrite Ahead Log预写日志文件大小超过默认上限200M。处理步骤检查结果集或事务是否未关闭关闭所有结果集或事务。这是典型的资源泄漏场景RDB 系统默认日志方式即为 WAL 模式若长期不关闭结果集/事务WAL 会持续膨胀直至超过 200M 上限。insert、update等写接口的异常表均列出 14800047。SQLite 底层错误14800021 ~ 14800034仓颉侧关系型数据库底层基于 SQLite 组件支持事务、索引、视图、触发器、外键、参数化查询和预编译 SQL 语句等特性因此一组错误码直接透传了 SQLite 的原生错误。每个错误码的可能原因末尾均注明了对应的 SQLITE_* 原生错误场景两者映射关系如下仓颉错误码SQLite 原生错误典型场景14800021SQLITE_ERROR插入/更新未创建的表、未定义的列或函数14800022SQLITE_ABORT自定义函数回调被中止14800023SQLITE_PERM无权限访问/修改数据库文件14800024SQLITE_BUSY数据库文件被其他进程/连接锁定14800025SQLITE_LOCKED表被锁定事务或锁机制阻止写入14800026SQLITE_NOMEM数据库内存不足14800027SQLITE_READONLY尝试写入只读数据库14800028SQLITE_IOERR磁盘 I/O 错误文件缺失、只读、磁盘满、文件损坏等14800029SQLITE_FULL数据库已满数据量过大或磁盘空间不足14800030SQLITE_CANTOPEN无法打开数据库文件14800031SQLITE_TOOBIGTEXT 或 BLOB 超出大小限制14800032SQLITE_CONSTRAINT违反完整性约束14800033SQLITE_MISMATCH数据类型不匹配14800034SQLITE_MISUSE库使用不正确14800021 SQLite通用错误SQLite: Generic error.执行 SQL 语句过程中出现错误如插入或更新未创建的表、插入或更新未曾有的列、调用未定义的函数等。处理步骤分析错误的 SQL 语句找出错误点。14800022 SQLite异步回调请求被中止SQLite: Callback routine requested an abort.通常发生在使用 SQLite 自定义函数机制时回调被中止执行。处理步骤检查 SQLite 的钩子函数callback的实现确保其正确性。14800023 SQLite访问权限被拒绝SQLite: Access permission denied.操作系统级别的权限问题SQLite 试图访问或修改一个文件但没有足够的权限。处理步骤确认文件没有只读属性如有则去掉检查文件与文件夹权限确保当前用户有足够权限读写检查文件系统是否为只读若是则改为可写状态确认没有其他进程锁定数据库文件如有则关闭占用文件的进程处理权限问题时确保自身有足够的权限去更改相关文件或文件夹权限。14800024 SQLite数据库文件已锁定SQLite: The database file is locked.可能原因同一应用两个进程如 UIAbility 与 datashareability同时打开同一数据库进行增删改操作或不同应用的同一 group 组内进程通过 group 组打开同一数据库进行增删改操作。处理步骤① 避免进程并发操作数据库② 等待一段时间重试。这与 RDB 的并发约束一致数据库同一时间只能支持一个写操作。14800025 SQLite数据库中的表被锁定SQLite: A table in the database is locked.可能原因尝试写入 SQLite 数据库时数据库文件已被另一个进程锁定可能因为数据库处于事务中或有其他锁机制阻止写入。处理步骤确保没有其他进程或线程正在对数据库文件进行写操作使用事务时确保开始事务后、提交事务前不进行任何写操作检查是否有其他锁机制如文件锁阻止写入确保数据库操作完成后正确关闭连接多线程环境下对数据库操作加锁防止竞争条件。14800026 SQLite数据库内存不足SQLite: The database is out of memory.数据量过大或内存分配不足导致。处理步骤减小数据量或增加内存分配。注意持久化指南的约束建议单次查询数据量不超过 5000 条、SQL 语句尽量简洁、合理分批次查询。14800027 SQLite尝试写入只读数据库SQLite: Attempt to write a readonly database.可能原因尝试写入以只读模式打开的数据库文件——文件权限问题、文件位于只读文件系统或数据库被标记为只读。处理步骤① 确保有足够权限写入数据库文件② 文件系统为只读时改为读写模式③ 确认打开数据库时未使用只读模式参数。注意StoreConfig.isReadOnly默认 false若置为 true则只允许读取写操作会返回错误码 801而rootDir配置的数据库也强制为只读模式。14800028 SQLite发生了某种磁盘 I/O 错误SQLite: Some kind of disk I/O error occurred.可能原因文件不存在、文件只读、磁盘空间不足、文件损坏等。处理步骤① 检查文件路径是否正确、文件是否存在② 确保文件未设置为只读③ 检查磁盘空间并清理释放空间④ 检查文件权限确保应用有足够权限读写。14800029 SQLite数据库已满SQLite: The database is full.数据量过大或磁盘空间不足导致数据库已满。处理步骤减小数据量或增加磁盘空间。14800031 SQLiteTEXT 或 BLOB 超出大小限制SQLite: TEXT or BLOB exceeds size limit.可能原因查询的结果集超过 SQLite 所能处理的大小限制。处理步骤将大查询分解为多个小查询每次处理一部分数据。仓颉侧 RDB 建议单条数据不超过 2M超出该大小可能出现插入成功但读取失败的情况与本错误码同属数据量超限问题。14800032 SQLite由于违反约束而中止SQLite: Abort due to constraint violation.可能原因写入时违反数据库完整性约束条件如主键冲突、NOT NULL、外键、唯一性约束等。处理步骤检查试图插入或更新的数据是否违反了上述约束。建表 SQL 中的约束定义如PRIMARY KEY、NOT NULL是此类错误的根源。14800033 SQLite数据类型不匹配SQLite: Data type mismatch.可能原因SQL 语句中涉及的数据类型与数据库中存储的数据类型不匹配。处理步骤检查 SQL 语句涉及的列的数据类型确保插入、更新或查询的数据类型与列的数据类型相匹配。注意仓颉侧RelationalStoreValueType枚举提供了Integer(Int64)、Double(Float64)、StringValue(String)、Boolean(Bool)、Uint8Array、Null、Asset等类型包装写入时应选用与列定义一致的包装类型。14800034 SQLite库使用不正确SQLite: Library used incorrectly.可能原因数据库操作或使用上下文不正确典型情况数据库未完成一个操作就进行下一个操作数据库连接关闭后继续对其操作使用了已释放或无效的数据库对象。处理步骤① 确保数据库操作之间有适当同步如锁或其他同步机制② 确保连接在使用前打开、操作结束后关闭③ 确保所有数据库对象使用完毕后正确释放。分布式与订阅相关错误14800050 获取订阅服务失败Failed to obtain subscription service.可能原因当前平台不支持订阅服务。处理步骤需要在当前平台部署订阅服务。14800051 分布式表类型不匹配The type of the distributed table does not match.可能原因对同一数据库表设置的分布式表类型前后不一致。分布式表类型见 DistributedType 枚举DistributedDevice在不同设备之间分布式与DistributedCloud在设备和云端之间分布式。处理步骤对同一数据库表设置的分布式表类型保持一致——属于端端同步的分布式表不可再设置为用于端云的同步表。错误码与接口异常表的对应关系排查错误码时可以借助 API 文档中的异常小节确认哪个接口会抛哪个错误码反向缩小问题范围。以 cj-apis-relational_store.md 为例getRdbStore源码位置14800000、14800010、14800011、14801001、14801002、14800017以及 14800020The secret key is corrupted or lost密钥损坏或丢失、14800021~14800023、14800027~14800030deleteRdbStore两个重载14800000、14800010、14801001、14801002backup / insert / update / delete / query / beginTransaction / commit / rollBack等操作类接口除 14800000、14800014、14800015 外主要集中抛出 14800021~14800034 这一组 SQLite 底层错误以及 14800047WAL 超限。其中 14800020 虽然出现在getRdbStore异常表中但错误码说明文档未单独展开此处仅作提示它对应加密数据库密钥损坏或丢失的场景可结合StoreConfig.cryptoParam与CryptoParam的加密参数配置理解。实战排查流程综合上述错误码分类遇到 RDB 异常时可按以下路径收敛问题先看错误码区间1480000x是模块内部/文件/结果集问题1480002x~1480003x是 SQLite 底层问题结合映射表对照 SQLITE_* 语义1480100x是 Stage 模型/参数配置问题1480005x是分布式/订阅问题结合日志确认14800000 这类兜底错误必须依赖日志细节无法靠重试解决时按SQL 语句 → 对象生命周期 → 接口用法 → 系统资源逐项排查检查对象生命周期结果集与事务是否及时close/commit/rollBack对应 14800014、14800047、14800034核对配置一致性encrypt、securityLevel、area、dataGroupId是否与首次建库一致对应 14800017、14801002检查文件与权限路径、只读属性、磁盘空间、文件锁定对应 14800010、14800023、14800027、14800028、14800029、14800030数据库损坏时重建恢复优先用备份restore恢复无备份则删库重建或将allowRebuild置为 true 自动重建对应 14800011。按照以上流程配合本仓库的关系型数据库错误码文档、API 参考与数据持久化开发指南即可系统化地定位并解决仓颉应用中几乎全部的关系型数据库异常。赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉语言实现关系型数据库RDB跨设备数据同步开发指南仓颉语言实现关系型数据库RDB跨设备数据同步开发指南 导读 在鸿蒙多设备组网场景中同一应用常常需要让手机、平板、智慧屏等设备共享同一份关系型数据。本文以文档知识库教程OpenHarmony仓颉 OpenHarmony 设置数据项模块错误码详解14800000 与 14800010 的排查与处理仓颉 OpenHarmony 设置数据项模块错误码详解14800000 与 14800010 的排查与处理 本篇基于仓颉语料库CangjieCorpus中文档知识库教程OpenHarmony仓颉 HTTP 数据请求错误码完全指南2300000 系列错误码解析与排查手册仓颉 HTTP 数据请求错误码完全指南2300000 系列错误码解析与排查手册 本文以 OpenHarmony 仓颉 API ohos.net.http N文档知识库教程OpenHarmony上一篇让Windows 11重获新生Win11Debloat系统优化工具完全指南下一篇kube-prometheus 版本发布流程完全指南从版本节奏到切分新版本创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考