企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

本篇技术指南以 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。也就是说，同一个错误码会出现在多个接口的异常表中，排查时应结合"当前调用的是哪个接口"与"错误码类型"双重定位。

错误码速查总表

内部错误与配置类错误

14800000 内部错误（Inner error.）

该错误是关系型数据库模块的兜底错误码，表示发生了无法归入其他错误码的内部异常。文档给出的可能原因包括四类：

1. SQL 执行异常；
2. 内部状态异常；
3. 错误地使用接口；
4. 系统级错误：空指针、内存不足、数据服务异常重启、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.。

处理步骤：

1. 如果之前备份过数据库，可尝试使用已备份的数据库文件恢复数据库；
2. 如果之前没有备份过数据库，可尝试删除数据库后重新创建。

数据持久化开发指南对 14800011 有专门提示："关系型数据库在操作或存储过程中，可能由于各种原因发生非预期异常（抛出14800011）。此时需要对数据库进行重建并恢复数据，以保障正常的应用开发。"这与StoreConfig.allowRebuild参数（默认 false，即异常时不自动删除重建）配合使用：若将该参数置为 true，则数据库异常时会被自动删除并重建一个空库空表。备份与恢复的具体操作参见关系型数据库备份与恢复，其中backup("Backup.db")与restore("Backup.db")分别用于手动备份与恢复。

14800030 SQLite：无法打开数据库文件（SQLite: Unable to open the database file.）

SQLite 无法打开数据库文件，可能原因：

1. 文件不存在，且创建新数据库失败；
2. 文件存在，但数据库文件损坏；
3. 文件权限问题，SQLite 无法读写文件；
4. 磁盘空间不足。

处理步骤：① 确认数据库文件路径是否正确、检查文件权限，确保应用有足够权限读写文件；② 确认磁盘空间足够。

结果集与列访问类错误

此类错误与ResultSet结果集的操作密切相关。ResultSet是调用query/querySql等查询接口后返回的结果集合，其游标默认指向第 -1 个记录，有效数据从 0 开始。

14800012 结果集为空或指定位置不合法（Row out of bounds.）

可能原因：结果集为空，或结果集指定行号超出位置范围[0, m - 1]，其中m = resultsetV9.rowCount。

处理步骤：检查当前操作得到的结果集是否为空，或指定的位置是否合法。对应ResultSet的行定位 API：rowCount（结果集总行数）、rowIndex（当前行索引）、goTo(row)、goToFirstRow()、goToLastRow()等，调用这些方法前应先确认行号落在有效范围内。

14800013 列值为空或列类型与当前调用接口不兼容（Column out of bounds.）

可能原因：

1. 结果集为空；
2. 结果集当前行号超出范围[0, m - 1]（m = resultsetV9.rowCount）；
3. 当前列号超出范围[0, n - 1]（n = resultsetV9.columnCount）；
4. 当前列数据类型接口不支持。

处理步骤：① 检查结果集是否为空；② 检查结果集当前行号、列号是否超出范围；③ 检查当前列数据类型是否支持。仓颉侧 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.）

可能原因：在开启读事务或结果集未关闭的情况下，不断执行增删改操作，导致 WAL（Write Ahead Log，预写日志）文件大小超过默认上限（200M）。

处理步骤：检查结果集或事务是否未关闭，关闭所有结果集或事务。这是典型的资源泄漏场景：RDB 系统默认日志方式即为 WAL 模式，若长期不关闭结果集/事务，WAL 会持续膨胀直至超过 200M 上限。insert、update等写接口的异常表均列出 14800047。

SQLite 底层错误（14800021 ~ 14800034）

仓颉侧关系型数据库底层基于 SQLite 组件（支持事务、索引、视图、触发器、外键、参数化查询和预编译 SQL 语句等特性），因此一组错误码直接透传了 SQLite 的原生错误。每个错误码的"可能原因"末尾均注明了对应的 SQLITE_* 原生错误场景，两者映射关系如下：

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 试图访问或修改一个文件但没有足够的权限。

处理步骤：

1. 确认文件没有只读属性，如有则去掉；
2. 检查文件与文件夹权限，确保当前用户有足够权限读写；
3. 检查文件系统是否为只读，若是则改为可写状态；
4. 确认没有其他进程锁定数据库文件，如有则关闭占用文件的进程；
5. 处理权限问题时确保自身有足够的权限去更改相关文件或文件夹权限。

14800024 SQLite：数据库文件已锁定（SQLite: The database file is locked.）

可能原因：同一应用两个进程（如 UIAbility 与 datashareability）同时打开同一数据库进行增删改操作，或不同应用的同一 group 组内进程通过 group 组打开同一数据库进行增删改操作。

处理步骤：① 避免进程并发操作数据库；② 等待一段时间重试。这与 RDB 的并发约束一致：数据库同一时间只能支持一个写操作。

14800025 SQLite：数据库中的表被锁定（SQLite: A table in the database is locked.）

可能原因：尝试写入 SQLite 数据库时，数据库文件已被另一个进程锁定，可能因为数据库处于事务中或有其他锁机制阻止写入。

处理步骤：

1. 确保没有其他进程或线程正在对数据库文件进行写操作；
2. 使用事务时，确保开始事务后、提交事务前不进行任何写操作；
3. 检查是否有其他锁机制（如文件锁）阻止写入；
4. 确保数据库操作完成后正确关闭连接；
5. 多线程环境下对数据库操作加锁，防止竞争条件。

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 SQLite：TEXT 或 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，以及 14800020（The secret key is corrupted or lost，密钥损坏或丢失）、14800021~14800023、14800027~14800030；
• deleteRdbStore（两个重载）：14800000、14800010、14801001、14801002；
• backup / insert / update / delete / query / beginTransaction / commit / rollBack等操作类接口：除 14800000、14800014、14800015 外，主要集中抛出 14800021~14800034 这一组 SQLite 底层错误，以及 14800047（WAL 超限）。

其中 14800020 虽然出现在getRdbStore异常表中，但错误码说明文档未单独展开，此处仅作提示：它对应加密数据库密钥损坏或丢失的场景，可结合StoreConfig.cryptoParam与CryptoParam的加密参数配置理解。

实战排查流程

综合上述错误码分类，遇到 RDB 异常时可按以下路径收敛问题：

1. 先看错误码区间：1480000x是模块内部/文件/结果集问题，1480002x~1480003x是 SQLite 底层问题（结合映射表对照 SQLITE_* 语义），1480100x是 Stage 模型/参数配置问题，1480005x是分布式/订阅问题；
2. 结合日志确认：14800000 这类兜底错误必须依赖日志细节，无法靠重试解决时按"SQL 语句 → 对象生命周期 → 接口用法 → 系统资源"逐项排查；
3. 检查对象生命周期：结果集与事务是否及时close/commit/rollBack（对应 14800014、14800047、14800034）；
4. 核对配置一致性：encrypt、securityLevel、area、dataGroupId是否与首次建库一致（对应 14800017、14801002）；
5. 检查文件与权限：路径、只读属性、磁盘空间、文件锁定（对应 14800010、14800023、14800027、14800028、14800029、14800030）；
6. 数据库损坏时重建恢复：优先用备份restore恢复，无备份则删库重建，或将allowRebuild置为 true 自动重建（对应 14800011）。

按照以上流程，配合本仓库的关系型数据库错误码文档、API 参考与数据持久化开发指南，即可系统化地定位并解决仓颉应用中几乎全部的关系型数据库异常。

• 文档
• 知识库
• 教程
• OpenHarmony