常见错误与解决方案

在开发、部署或运行应用时，您可能会遇到系统抛出的异常提示或不符合预期的错误结果。我们为您分类整理了所有的错误现象与解决方案，您可以根据当前遇到的场景切换对应标签页进行排查。

建议结合实际业务场景 and 错误提示，优先排查权限、配置、数据唯一性等常见问题。如遇无法解决的问题，可联系 Zion 官方技术支持。

编辑与开发时错误

编辑时常见错误排查

在编辑器中进行开发时，系统会对配置进行智能校验。

典型表现：编辑器右上角错误图标有数字显示。
处理办法：点击“去修复”跳转到错误位置，根据报错提示修改。

常见高频校验异常

在实际搭建中，最常遇到的两类高频校验异常如下：

1. 类型错误（Type Error）

错误表现：字段的数据类型与填入/绑定的数据类型不匹配。
典型案例：数据表中“原价”字段需为 Int（整数）类型，但前端输入框或配置中直接填入了字符串 "1元"。
解决方法：去掉带有非数字的字符（如 "元"），仅填入纯数值 1。
错误图示：

2. 必填项缺失（Missing Required Field）

错误表现：组件、API 行为、或数据模型中被声明为“必填”的属性、入参未进行填写或数据绑定。
典型案例：配置“创建数据”行为时，必填的“名称”字段未配置对应的数据源绑定。
解决方法：检查该组件或行为属性，为其绑定正确的变量 or 输入值。
错误图示：

编辑器校验错误对照表

报错信息	导致原因	一般解决方法
数据模型 `$tableName` 里没有 `$fieldName` 属性，需在数据表内添加该类型字段后重新配置	数据模型中某个字段被删除，绑定这个字段的组件找不到依赖源	点击“去修复”删除原来配置，根据需求重新配置新的字段后再进行绑定
未知表名 `$tableName`	引用了不存在的表名	1. 检查表名拼写 2. 重新选择有效的数据表 3. 如果不再使用，删除该引用
未知表 id `$tableId`	引用了不存在的表 ID	1. 检查表 ID 是否正确 2. 重新选择有效的数据表 3. 如果不再使用，删除该引用
数据库触发器 `$triggerName` 未配置数据表	数据库触发器没有配置目标数据表	为该触发器配置一个有效的数据表
未知主题 `$colorThemeId`	使用了不支持的主题颜色	重新选择主题颜色
未知变量类型 `$type`	使用了未定义或不支持的变量类型	检查变量类型，确保使用系统支持的变量类型
重复类型定义 `$type`	同一种类型被重复定义	检查并删除重复的类型定义
约束名 `$constraintName` 与表 `$tableName` 的表名冲突	约束名称与表名相同	修改约束名称，避免与表名冲突
约束名 `$constraintName` 与表 `$tableName` 的列名冲突	约束名称与列名（字段名）相同	修改约束名称，避免与列名冲突
表 `$tableName` 中唯一约束 `$constraintName` 未配置列	唯一约束没有配置任何列	为该唯一约束添加至少一列
未提供 API	第三方 API 定义缺失	配置完整的第三方 API
API `$definitionId` 不存在	引用了不存在的 API	重新选择新的第三方 API，如果不再使用，则删除该引用
API `$definitionId` 返回中不存在 `$fieldName` 字段	API 返回结构中缺少预期的字段	1. 检查 API 文档，确认返回字段 2. 修改字段绑定或更新 API 定义
参数 `$fieldName` 不在表 `$tableName` 里，表的参数: `$existField`，需删除或重新配置	引用了数据表中不存在的字段	检查字段名是否正确，使用已存在的有效字段
请求行为 `$mutationId` 数据绑定丢失，需重新设置请求行为	请求行为的数据绑定配置丢失或被删除	重新设置该请求行为的数据绑定
自定义行为 `$actionFlowId` 不存在	引用了不存在的自定义行为流	重新创建该行为流或删除引用
ZAI 行为 `$configId` 不存在	引用了不存在的 ZAI 行为	重新创建 ZAI 行为或删除引用
字段 `$fieldName` 不存在自定义行为 `$actionFlowId` 里，现有字段: `$existField`	自定义行为中不存在该字段	检查字段，使用已存在的有效字段
字段 `$fieldName` 不存在 ZAI 行为 `$configId` 里，现有字段: `$existField`	ZAI 行为中不存在该字段	检查字段，使用已存在的有效字段
行为缺少页面入参	行为配置中缺少必要的页面入参	在页面配置中补充页面入参
行为中的路径入参 `$pathDataName` 在目标页面 `$targetPage` 中不存在	目标页面没有定义该路径入参	1. 检查目标页面的路径参数配置 2. 添加对应路径参数或修改行为配置
输入数据源 `$componentId` 丢失	输入组件的数据源对应的组件丢失	1. 检查组件是否存在 2. 重新选择输入数据源
代码组件 `$componentId` 丢失	代码组件丢失或被删除	1. 检查组件是否存在 2. 重新配置或删除引用
webhook 请求体丢失	Webhook 请求体配置丢失或被删除	重新配置 Webhook 请求体
组件 `$componentId` 不存在	某个组件不存在	重新创建该组件或删除引用
页面变量 `$pageDataName` 丢失	页面变量被删除或未定义	重新创建该变量或删除引用
引用的数据源 `$remoteDataId` 丢失	引用的页面数据源不存在	重新创建该数据源或删除引用
定时任务控制行为缺少目标任务	定时任务控制行为没有配置目标任务	配置一个有效的定时任务
定时任务控制行为的目标定时任务 `$scheduledJobId` 不存在	引用了不存在的定时任务	重新创建该定时任务或删除引用
设置 JSONB 数据行为的目标 JSON 配置错误，该项只支持页面变量	配置了不支持的数据源（非页面变量）	将目标 JSON 配置为页面变量
设置折叠模式行为中未选择模式	折叠模式行为未配置模式选项	在行为配置中选择一个模式（展开/折叠）
配置数据路径中的 `componentMRef:$componentMRef` 无效	数据路径中引用了无效的组件	检查组件引用，确保组件存在 or 重新配置
客户端变量 `$globalDataName` 丢失	客户端变量被删除或未定义	重新创建 or 删除引用
页面入参 `$linkedDataName` 缺失	页面入参配置缺失	在页面配置中重新添加该页面入参
未知页面入参: `$linkedDataName`	引用了未定义的页面入参	在页面配置中定义该页面入参或删除引用
路径入参 `$pathDataName` 缺失	页面入参的路径入参配置缺失	在页面配置中添加该路径入参
绑定数据路径中的类型与实际类型不符	绑定的数据类型与预期不符	检查绑定的数据路径，确保类型匹配
选择视图的本地数据 `$componentId` 缺失	选择视图的本地数据源丢失	重新配置选择视图的本地数据源
待刷新组件 `$componentId` 缺失	待刷新的页面 or 列表丢失或被删除	检查后重新选择待刷新组件
刷新行为目标 `$componentId` 为其他页面的组件，请更改刷新目标	刷新目标组件不在当前页面	将刷新目标更改为当前页面内的组件
不支持刷新使用了本地数据源的列表	试图刷新一个使用本地数据源的列表，但系统不支持	避免此操作，或更改数据源类型
行为流节点 `$nodeId` 数据绑定丢失	行为流节点的数据绑定配置丢失	重新配置该节点的数据绑定
输入数据参数丢失	输入数据参数未配置	配置输入数据参数
未知工具 `$toolId`	引用了不存在的工具	检查工具，确保工具存在
未知上下文请求 `$requestId`	引用了不存在的上下文请求	检查请求，确保请求存在
行为所需组件 `$mRefId` 不存在	行为引用了不存在的组件	重新创建该组件或删除引用
行为的目标组件不是页面	行为的目标组件类型错误（应该是页面）	将目标组件更改为页面
底部导航栏上的组件 `$mRefId` 不存在	底部导航栏引用了不存在的组件	重新创建 or 删除该引用
底部导航栏的内容不能以 ’@’ 开头	底部导航栏的项内容以 ’@’ 开头，这是不允许的	修改内容，避免以非法字符开头
无效的输入组件: `$mRefId`	输入组件无效 or 不存在	重新创建该组件 or 删除该组件
无效的表格组件: `$mRefId`	表格组件无效 or 不存在	重新创建该组件 or 删除该组件
聚合数据来源不是数据模型，无法使用过滤条件	在本平台创建的数据模型才能使用聚合数据	重新配置该聚合数据 or 删除
在组件 `$graphString` 中发现循环依赖	组件之间存在循环依赖关系	检查组件依赖关系，打破循环（如移除不必要的依赖）
属性 `$fieldName` 不可用	引用了不可用的字段	检查字段名，确保可用
绑定数据不在表作用域内	数据绑定超出了当前表的作用域	重新配置数据绑定，确保在正确的表作用域内
过滤条件的值没有配置或配置的类型错误（应该是布尔值）	过滤条件配置了非布尔值	1. 检查过滤条件的值是否为布尔类型 2. 修改或删除该过滤条件
公式参数类型不匹配	公式中的参数类型不匹配	检查绑定的参数类型，确保与公式要求一致
自定义对象的项: `$fieldName` 值不能为空	自定义对象的字段值为空	为该字段配置有效的非空值
组件 `$componentId` 的子项的第 index 个标题缺失	组件的子项某个标题缺失	为子项配置标题
进度条中总进度必须是步进值的整数倍	总进度值 and 步进值不匹配	调整总进度 or 步进值，使总进度是步进值的整数倍
导航操作缺失参数 `$paramName`	跳转操作缺少必要的参数	在跳转操作配置中补充相应参数
修改数据操作配置错误	修改数据操作的配置有误	检查修改数据操作的配置并进行修正
暂时不支持删除可重复列表中的值	试图删除可重复列表的值，但当前不支持	避免此操作
扫描二维码的赋值类型不支持 `$receiverType`，只允许文本，布尔值，数字 and 日期/时间类型	赋值参数类型不符合要求	将赋值参数类型更改为文本、布尔值、数字 or 日期/时间类型
条件行为 `$actionId` 的条件需配置布尔类型的数据	条件行为的条件配置中参数不是布尔类型	将该项参数配置为布尔类型
条件数据没有以 ‘总是’ 作为最后的条件	条件数据缺少 ‘总是’ 分支作为默认情况	在条件数据末尾添加 ‘总是’ 分支
条件数据中的第 `$index` 项需配置正确类型值	条件数据中某一项的值类型错误	检查并配置正确的值类型
条件行为没有以 ‘总是’ 作为最后的条件	条件行为缺少 ‘总是’ 分支	在条件行为末尾添加 ‘总是’ 分支
条件式容器 `$componentId` 的条件需配置布尔类型的数据	条件式容器的条件不是布尔类型	将条件配置为布尔类型的数据
条件数据中的第 `$index` 项需配置布尔类型的数据	条件数据中某一项的条件配置中参数不是布尔类型	将该项参数配置为布尔类型

部署与运行时错误

部署与发布异常排查

典型表现：点击“更新预览”报错，或者部署后端服务时提示失败。

在项目部署 or 发布过程中，最常见的高频异常主要分为以下两类：

1. 更新预览报错

当点击右上角“更新预览”按钮时，系统在打包构建前端 or 编译时抛出异常。

处理流程：
1. 仔细阅读弹窗中展示的详细错误信息（通常包含具体的组件、变量 or 字段名）。
2. 根据报错提示回到对应位置进行修复（如引用的组件已被删除、数据绑定引用失效等）。
3. 若无法理解报错，可点击右上角咨询内置的 AI 智能助手。
4. 仍无法解决时，请联系 Zion 官方技术支持。
常见图示：

2. 同步后端失败

在同步数据模型 or 部署后端算力服务时发生异常。

处理流程：
- 无需手动排查，直接点击报错弹窗下方的 “上报” 按钮。
- Zion 官方值班工程师会在后台自动接收到异常日志并协助进行处理。
常见图示：

运行时与部署错误对照表

报错信息	解释	导致原因	一般解决方法
`Permission check failed`	权限检查失败	当前用户无执行该操作的权限	前往权限配置处检查对应操作权限
`duplicate key value violates unique constraint`	唯一约束冲突	数据模型有约束字段添加了重复值	检查添加数据是否重复，确保其符合业务逻辑
`delete or update must has filter`	缺少过滤条件	未添加过滤条件	检查过滤条件设置
`TABLE_ACCESS`	表访问受限	当前用户对某表无访问权限	检查权限配置
`Action flow not found`	找不到行为流	行为流创建后未部署	部署后再执行
`ANOTHER_APP_IS_DEPLOYING`（项目部署中，请稍候）	项目部署中	后端 or 客户端正在部署，重复发起部署请求	等待部署完成后重试
`WECHAT_APP_ID_AND_SECRET_REQUIRED`（部署失败，请绑定微信后再试）	微信配置缺失	微信部署未提供 `appId`/`secret`	绑定后重试
`CANNOT_DEPLOY_AN_OLDER_SCHEMA`（部署失败，请重试）	部署失败	未使用最新 schema 部署	刷新页面后重试
`PROJECT_ENV_CONFIG_SYNC_ERROR`（数据同步失败）	数据同步失败	部署服务端时数据同步失败	刷新页面后重试
`TARGET_PLATFORM_IS_DEPLOYING`（项目部署中，请稍后）	平台部署中	单项目部署过程中发现同一 `build_target` 正在部署	等待部署完成后重试
`NO_PROJECT_WECHAT_APP_CONFIG`（部署失败，缺少必要配置项）	配置缺失	微信小程序部署缺少配置项	绑定后重试
`SUPPORT_SERVICE_IS_DEPLOYING`（后端部署中，请稍候）	后端部署中	后端部署过程中重复部署	等待部署完成后重试
`TABLE_NAME_TOO_LONG`（表名太长，请修改）	表名过长	表名超出 62 个字符	缩短表名
`TABLE_NAME_ALREADY_EXISTS`（表名已存在，请修改）	表名重复	表名已存在	修改表名

微信场景专属报错

小程序包体积超限

问题描述

发布微信小程序时提示包体积超限，无法正常发布。

常见报错

提示项目分包过大 or 主包过大。

解决方案

1. 了解分包限制

微信小程序对包体积有严格限制：

主包：最大 2M（包含底部导航页）
分包：每个分包最大 2M，最多 100 个分包
总体积：所有分包总大小不得超过 20M

2. 优化分包结构

主包页面：包含底部导航栏内的页面（含主页面）
分包页面：除主包外的其他页面

举例：项目有 40 个页面，底部导航页 4 个，主包页面共 5 个，则主包含 5 个页面，其余页面分为多个分包。

3. 具体优化措施

减少主包页面数量：注意要保证主包页面数 ≥ 底部导航页数。操作步骤：预发布 → 设置 → 主包/分包页面数量设置 → 保存
避免滥用条件式容器：优先用条件数据
减少复杂视图组件使用：复杂业务建议新建页面实现

4. 测试对比

不同方式生成相同数据，页面体积对比：

小程序运行时出现权限错误

问题描述

小程序运行时提示权限不足，无法访问数据 or 功能。

常见报错

User xxx has no permission for SELECT on ud_zionbangzhuwendang_cd2170

解决方案

进入权限配置
为对应角色（已登陆用户、游客等）配置数据表的查询权限
检查 API、行为流 or AI 行为的使用权限

小程序出现网络错误

问题描述

扫码进入小程序后立即出现网络错误。

常见报错

network error / Unknown error

解决方案

清除缓存：删除小程序，重新扫码进入
检查配置：如果依然报错，说明首页配置有问题
查看详细错误：使用调试方法查看具体报错信息

数据修改操作失败

问题描述

执行数据修改操作时出现服务器内部错误。

常见报错

server internal error

解决方案

检查修改表数据配置，确保配置的字段数据不为空。update（修改）操作不允许任何字段值都为空。

参数类型错误

问题描述

执行操作时出现参数类型验证错误。

常见报错

Validation error of type Wrong Type: argument xxxxx

解决方案

找到触发该行为的位置
重新进行修改表数据行为的数据绑定
确认所绑定的数据一定有正确类型的值

行为流运行超时

问题描述

行为流运行后一直转圈（加载中），无法完成。

问题原因

基础版项目服务器算力资源有限，仅能支持 15s 的行为流运行时间。

解决方案

简化逻辑：简化行为流处理逻辑
升级版本：将项目升级至高级版及以上版本

如何获取小程序的 AppID

问题描述

需要获取其他小程序的 AppID 用于跳转 or 配置。

解决方案

手机端获取

打开跳转目标的小程序
点击右上角查看详细信息
点击更多资料即可看到 AppID

小程序 AppID 获取示例

电脑端获取

进入小程序后台
工具 → 生成小程序码
点击更多资料查看 AppID

小程序码生成示例

如何获取小程序页面路径

问题描述

需要获取小程序内特定页面的路径用于跳转配置。

解决方案

进入小程序的目标页
点击右上角
点击“复制页面路径”即可获取

⚠️

iOS 暂不支持复制页面路径的方法。
复制后会得到一个带有 .html 后缀的路径，输入路径时要删除这个后缀。
正确示例：pages/kf2ao6q9/kf2ao6q9
错误示范：pages/kf2ao6q9/kf2ao6q9.html

如何使用小程序的 vConsole 调试

问题描述

小程序出现报错，但不知道具体原因，需要查看详细错误信息。

解决方案

1. 开启调试模式

点击手机小程序右上角
点击 debug 模式按钮，确认进入 debug 模式

2. 查看报错信息

重新进入小程序，页面中会出现【vConsole】按钮
点击该按钮，查看小程序中的所有请求内容 and 报错信息

如果报错出现在某些操作之后，建议在最终触发报错的上一步操作时，先点击【Clear】按钮清除之前的请求数据，然后再触发报错，最后查看具体报错信息。

3. 定位报错位置

一般报错信息会出现在某个 result 指向的 Object 里，点击展开查看详细内容即可找到报错信息。