> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作流故障排除

> 常见工作流问题及其解决方法。

## 常见问题及解决方案

### 工作流未触发

**症状**：您的工作流未在您预期的时间运行。

**可能原因**：

1. **工作流未激活**：请确保工作流设置为 "Active" 而非 "Draft"
2. **未满足触发条件**：请确认触发器与您期望的事件匹配
3. **字段未被监控**：对于 "Record is Updated" 触发器，请确保正在监控特定字段
4. **权限**：检查您是否具有运行工作流的权限

**解决方案**：

* 在工作流列表中核实工作流状态
* 使用您期望触发它的特定操作进行测试
* 检查触发器配置
* 就权限问题联系您的管理员

### 工作流触发过早（字段为空）

**症状**：在 UI 中手动创建记录时，您的工作流会在您填完所有字段之前就被触发。 工作流在大多数字段值为空的情况下运行。

**原因**：Twenty 实时保存所有内容——不存在单独的 "edit" 与 "read" 模式。 当您创建一条记录时，它会立即被保存，在您填写其他字段之前就触发 "Record is created" 事件。

**当 "Record is created" 效果良好时**：

* 通过 API 调用创建的记录（字段在单个请求中填充）
* 通过导入创建的记录
* 由其他工作流自动创建记录

**解决方案**：对于在 UI 中手动创建的记录，请改用 **"Record is created or updated"** 作为触发器。 这样一来：

* 工作流会在用户完成填写并保存字段后再触发
* 您将获得完整的数据，而不是空值

<Tip>
  如果您只希望每条记录的工作流仅运行一次，请添加一个 Filter 操作以检查某个字段，例如 `createdAt equals updatedAt`（首次保存），或使用自定义复选框字段来跟踪该工作流是否已运行。
</Tip>

### 操作失败

**症状**：工作流已运行，但部分操作失败。

**可能原因**：

1. **数据缺失**：必填字段为空
2. **引用无效**：来自前面步骤的变量不存在
3. **API 错误**：外部服务返回错误
4. **权限问题**：该操作需要您不具备的权限

**解决方案**：

* 在工作流运行详情中查看错误消息
* 确认所有必填字段都有值
* 单独测试 API 连接
* 检查角色权限

### HTTP 请求错误

**症状**：HTTP 请求操作失败或返回意外结果。

**常见错误代码**：

* **400**: 错误请求 - 检查请求正文格式
* **401**: 未授权 - 验证 API 密钥
* **403**: 禁止访问 - 检查 API 权限
* **404**: 未找到 - 核实端点 URL
* **429**: 请求过多 - 实施速率限制
* **500**: 服务器错误 - 外部服务问题

**解决方案**：

* 核实 API 端点 URL
* 检查身份验证请求头
* 先在 Twenty 之外测试该 API 调用
* 在 Code 操作中添加错误处理

### Code 操作错误

**症状**：JavaScript 代码执行失败。

**常见问题**：

1. **语法错误**：拼写错误或无效的 JavaScript
2. **未定义的变量**：引用了不存在的变量
3. **类型错误**：对错误的数据类型进行操作
4. **超时**：代码执行时间过长

**解决方案**：

* 使用内置代码编辑器的校验功能
* 先在 JavaScript 控制台中测试代码逻辑
* 添加 console.log 语句进行调试
* 简化复杂操作

### 电子邮件无法发送

**症状**：Send Email 操作未能投递电子邮件。

**可能原因**：

1. **未连接电子邮件账户**：检查 Settings → Accounts
2. **无效的电子邮件地址**：收件人电子邮件格式错误
3. **发送限制**：已达到电子邮件服务商的速率限制
4. **垃圾邮件过滤器**：电子邮件被拦截

**解决方案**：

* 确认电子邮件账户连接正常
* 校验收件人电子邮件地址
* 检查电子邮件服务商的限制
* 检查电子邮件内容是否包含垃圾邮件触发因素

## 调试工作流

### 使用工作流运行

1. 进入工作流编辑器
2. 打开 **Runs** 面板
3. 找到失败的运行
4. 点击查看逐步详情
5. 查看错误消息和输出数据

### 测试单个步骤

1. 对于 Code 操作，使用 **Test** 按钮
2. 对于 HTTP 请求，请单独测试该端点
3. 创建测试记录以触发工作流
4. 使用手动触发器进行可控测试

### 常见调试模式

**添加日志**：
使用 Code 操作记录中间值以进行调试。

**隔离步骤**：
独立测试每个步骤以定位失败。

**检查数据流**：
确认每个步骤都接收到预期的输入数据。

## 避免问题的最佳实践

### 激活前

* 在草稿模式下进行充分测试
* 验证所有 API 连接
* 仔细检查触发条件
* 记录预期行为

### 开发过程中

* 使用具有描述性的步骤名称
* 在 Code 操作中添加注释
* 使用真实数据进行测试
* 考虑边界情况

### 激活后

* 密切监控初始运行
* 设置失败告警
* 定期查看运行历史
* 尽可能保持工作流简洁