Troubleshooting

本页按报错入口定位 Perago 问题。优先用 perago check 复现 task module 和本机配置问题；perago check 通过后，再排查 perago extract、TaskDef 注册和 perago start 的运行时问题。

Triage Flow

从仓库根目录按这个顺序缩小问题范围。下面使用仓库内测试 fixture；真实部署时把 app.workers.features_build 换成自己的 task module target。

PYTHONPATH=tests/fixtures uv run perago check app.workers.features_build
PYTHONPATH=tests/fixtures uv run perago extract app.workers.features_build --output generated/features.build.json
PYTHONPATH=tests/fixtures uv run perago start app.workers.features_build -j 1

停在哪一步	主要问题范围	下一步
check 失败	task module、Pydantic contract、WorkspaceSpec、TaskControls 或本机 runtime config	先看 stderr 的 error: ...；修正代码或 .env 后重跑 check。
extract 失败	check 覆盖的范围，或输出路径缺少 .json 后缀	确认输出路径指向 JSON 文件。
start 失败	Conductor 连接变量、workspace task 的 LakeFS 连接变量、Conductor TaskDef 注册、worker supervisor 启动前检查	先确认 .env 满足 task 类型要求，再确认 TaskDef 已注册到 Conductor。
attempt 运行中失败	Conductor input、LakeFS workspace、Workspace Check、task body、publish fence 或 cleanup	结合 Conductor result status、reasonForIncompletion 和 worker JSONL 日志排查。

Task Module Cannot Load

错误文本	常见原因	修复
module target must be a Python import path, not a file path or object path	CLI target 写成 app/workers/foo.py、module:app 或空值。	使用 Python module import path，例如 app.workers.features_build。
<module> does not declare a Perago task	module 导入成功，但没有执行任何 @task(...) decorator。	确认文件中 exactly one function 被 @task(name=..., owner_email=...) 装饰。
<module> declares more than one Perago task	一个 Python module 中注册了多个 Perago task。	拆成多个 single-task module；不要用 --task 或 app registry 在同一文件中选择任务。

Perago 的 worker 单元是 exactly one task per Python module。一个 worker process 只服务这个 task name。

Task Definition Errors

错误文本	常见原因	修复
task name is required	@task(name=...) 为空字符串。	配置非空 task name。
task name must not contain path separators	task name 含 / 或 \。	task name 用 Conductor task 名称，不要用路径。
owner_email is required	owner_email 为空字符串。	填写负责人的邮箱或内部 owner 标识。
unsupported task decorator fields: ...	@task(...) 使用了未支持的 keyword。	只使用 name、owner_email、description、workspace、controls。
workspace must be a WorkspaceSpec	workspace= 传入了 dict 或其他对象。	使用 WorkspaceSpec(...)。
controls must be a TaskControls	controls= 传入了 dict 或其他对象。	使用 TaskControls(...) 和嵌套 policy model。
publish_budget requires workspace=WorkspaceSpec(...)	workspace-free task 配置了 publish budget。	只在 workspace task 上配置 TaskControls(publish_budget=...)。
WorkspaceSpec(read_only=True) disables workspace publication; TaskControls.publish_budget is ignored.	read-only workspace task 配置了 publish budget。	这是启动/校验阶段 warning；删除 publish_budget，或把 task 改为可写 workspace task。

这类错误在 module import 或 build_taskdef(...) 阶段暴露；perago check 会先加载 runtime config，再导入 task module。

Task Function Shape

错误文本	常见原因	修复
task function must be a synchronous function	task body 定义为 async def。	改成普通 def；MVP worker 不运行 async task function。
task function must not use *args, **kwargs, or keyword-only fields	签名使用 variadic 或 keyword-only 参数。	使用精确签名 (workspace: Path, params: ParamsModel) 或 (params: ParamsModel)。
task function parameters must not declare defaults	params 或 workspace 参数有默认值。	删除默认值；required/optional 字段只在 Pydantic model 内表达。
workspace task parameters must be named workspace and params	workspace task 的两个参数名不匹配。	顺序和名称都写成 workspace, params。
workspace must be annotated as pathlib.Path	workspace 未标注为 Path 或使用了其他类型。	使用 from pathlib import Path 并标注 workspace: Path。
workspace task functions require workspace=WorkspaceSpec(...)	函数签名像 workspace task，但 decorator 没声明 workspace。	在 @task(...) 里加入 workspace=WorkspaceSpec(...)。
workspace-free task parameter must be named params	workspace-free task 的唯一参数不叫 params。	把唯一参数命名为 params。
workspace-free task functions must not declare workspace=WorkspaceSpec(...)	函数只有 params，但 decorator 声明了 workspace。	删除 workspace=...，或把函数改成 workspace task 签名。
params must be annotated as a Pydantic BaseModel subclass	params 缺少类型注解，或类型未继承 Pydantic BaseModel。	定义 class Params(BaseModel): ... 并标注 params: Params。
return value must be annotated as a Pydantic BaseModel subclass	返回值缺少类型注解，或类型未继承 Pydantic BaseModel。	定义 output model 并标注 -> Output。

不要把业务字段展开成多个函数参数。函数签名只声明 Perago contract；业务 required/optional 字段属于 Pydantic Params 和 Output model。

WorkspaceSpec And Workspace Checks

错误文本	常见原因	修复
WorkspaceSpec.prefix must use '/' separators	prefix 使用了 Windows 反斜杠。	使用 POSIX 风格 /。
WorkspaceSpec.prefix must stay inside the repository	prefix 含 ..、. 或空 segment。	使用 / 或 repository 内的相对 prefix，例如 datasets/raw。
read-only task 写了本机 workspace 但没有发布	WorkspaceSpec(read_only=True) 禁止 workspace publication。	这是预期行为；写入会随 attempt-local cleanup 丢弃。
workspace guardrail paths must not be empty	require_file("") 或类似空路径。	填写 workspace-prefix 内的相对路径。
guardrail paths must be relative to WorkspaceSpec(prefix=...)	guardrail path 以 / 开头。	删除开头 /，路径相对于 WorkspaceSpec.prefix。
absolute guardrail paths are not allowed	使用了绝对 Path。	使用 workspace-relative path。
drive-qualified or absolute guardrail paths are not allowed	使用 Windows drive path。	使用不含 drive/root 的相对路径。
string guardrail paths must use '/' separators	字符串路径使用 \。	使用 /。
guardrail min_count must be <= max_count	require_glob(..., min_count=5, max_count=2)。	调整 count bounds。

运行中 Workspace Check 失败会进入 reasonForIncompletion：

错误文本	状态	含义
pre guardrail require_file('...') did not find a file	FAILED_WITH_TERMINAL_ERROR	输入 workspace 缺少 task 声明的必需文件。
pre guardrail require_glob('...') matched 0 files; min_count=1	FAILED_WITH_TERMINAL_ERROR	输入 workspace glob 数量不足。
post guardrail forbid_glob('...') matched N files	FAILED	task body 产出的 workspace 文件未通过 post check。

pre check 和任务显式抛出的 TaskTerminalError 会映射为 FAILED_WITH_TERMINAL_ERROR。post check、TaskFailed、未知业务异常和 publish 失败都会映射为普通 FAILED。

Runtime Configuration

错误文本	常见原因	修复
CONDUCTOR_SERVER_URL is required for perago start	perago start 没有 Conductor endpoint。	在 .env 或进程环境配置真实 CONDUCTOR_SERVER_URL。
LakeFS config is required for workspace tasks	启动 workspace task worker 时三个 LakeFS 变量都没配置。	workspace task 需要配置 LAKECTL_SERVER_ENDPOINT_URL、LAKECTL_CREDENTIALS_ACCESS_KEY_ID、LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY；workspace-free task 不需要 LakeFS。
LakeFS config is incomplete; missing ...	只配置了部分 LakeFS 变量。	三个 LakeFS 变量同时配置；如果当前命令和 task 类型不需要 LakeFS，就三个变量全部省略。
<NAME> must be replaced with a real value	连接变量仍是 replace-me。	用真实部署值替换占位值。
<path> is not writable: ...	workspace/log root 不可创建或不可写。	修正 PERAGO_WORKSPACE_ROOT 或 PERAGO_LOG_ROOT 的目录权限。
PERAGO_LOG_FILE_MAX_SIZE must be a positive size ...	日志大小格式错误。	使用 512KB、100MB 或 1.5GB。
PERAGO_LOG_RETENTION must be a positive day count ...	日志保留期格式错误。	使用 7d 或 30d。
PERAGO_WORKER_ID_PREFIX must contain only ASCII letters and digits	worker id prefix 含连字符、下划线、点号或非 ASCII 字符。	使用只含字母数字的前缀，例如 prodAFeaturesBuild。
PERAGO_WORKSPACE_GC_TTL must be a positive duration ...	workspace GC TTL 格式错误。	使用 30m、1h、24h 这类正数 duration。
PERAGO_WORKSPACE_GC_INTERVAL must be a positive duration ...	workspace GC interval 格式错误。	使用 30s、5m、1h 这类正数 duration。
PERAGO_SHUTDOWN_FORCE_KILL_AFTER must be a positive duration ...	shutdown force-kill deadline 格式错误。	使用 30s、5m、1h 这类正数 duration，或不配置该变量。

perago check 和 perago extract 不要求 Conductor/LakeFS 连接变量完整，但会拒绝半套 LakeFS 配置和不可写本机目录。perago start 始终要求 Conductor endpoint；只有 workspace task start 要求完整 LakeFS 配置。

TaskDef Registration

错误文本	常见原因	修复
output must be a JSON file path	perago extract --output 指向目录或非 .json 文件。	指向具体 JSON 文件，例如 generated/features.build.json。
Conductor TaskDef '<name>' is not registered; run perago extract and register it before start	perago start 前 Conductor 中没有同名 TaskDef。	运行 perago extract 生成 TaskDef JSON，并用部署流程注册到 Conductor。
failed to validate Conductor TaskDef: ...	启动前连接 Conductor 或查询 TaskDef 失败。	检查 CONDUCTOR_SERVER_URL、网络、认证和 Conductor 服务状态。

perago extract 只生成 TaskDef JSON，不会自动写入 Conductor。perago start 在启动 supervisor 前会真实检查 TaskDef 是否已注册。

Attempt Input And Result Validation

错误文本	常见原因	修复
workspace task input must contain only workspace and params	workspace task input 顶层字段缺失或多了其他字段。	input 顶层只保留 workspace 和 params。
workspace-free task input must contain only params	workspace-free task input 顶层包含 workspace 或其他字段。	input 顶层只保留 params。
workspace repository, branch, and ref must not be blank	WorkspaceInput 的 repository、branch 或 ref 是空白字符串。	填写非空 LakeFS repository、target branch 和 input commit ref。
Extra inputs are not permitted	Pydantic input/result model 收到未声明字段，或 control object 有未知字段。	删除额外字段；扩展 contract 必须先改 Pydantic model。
Input should be ...	Pydantic 字段类型不匹配。	按 generated TaskDef schema 和 Pydantic model 修正字段类型。

Workspace task 的 workspace 是平铺的 repository、branch、ref_type、ref 四元组；LakeFS endpoint、credentials、WorkspaceSpec.prefix 和 WorkspaceSpec.read_only 不属于 workflow input。

Workspace Sync And Publication

错误文本或现象	常见原因	修复
workspace publication does not support symlinks: ...	attempt-local workspace 中包含 symlink。	输出真实文件；不要把 symlink 发布到 LakeFS。
cannot publish from input ref <input-ref>; target branch <branch> current head is <current-head>	diff 非空 publication 前，target branch HEAD 既不是 input ref，也不是 input ref 的直接子提交。	不要手动重试同一 attempt；从当前 target branch head 发起新的 workflow。
cannot complete no-op from input ref <input-ref>; target branch <branch> current head is <current-head>	可写 no-op completion 前，target branch HEAD 不符合 HEAD == input_ref 或 parent(HEAD) == input_ref 协议。	不要把当前 no-op attempt 包装成成功；从当前 target branch head 重新发起 workflow。
可写 task 没有产生新 commit	read_only=False 但 workspace diff 为空。	这是 no-op completion；Perago 不会创建 empty commit，output ref 保持 input ref。
LakeFS download/stage/merge SDK 异常	repository/ref 不存在、凭证错误、网络失败或 LakeFS 服务异常。	检查 LakeFS 连接变量、repository、input commit 和 worker JSONL。
staging branch create 失败且 branch 已存在	同一个 execution id 的 staging branch 已存在，或远端残留与当前 execution id 冲突。	当前 attempt 会 fail closed。正常情况下每次 execution 都有唯一 branch；排查 worker 日志中的 execution_id，必要时清理残留 perago-staging-...-exec-... branch。
failed to clean staging workspace	staging branch 删除失败。	原始 task result 不会被覆盖；事后检查并清理 perago-staging-... branch。
failed to clean attempt-local workspace	本机 attempt workspace 删除失败。	原始 task result 不会被覆盖；检查 PERAGO_WORKSPACE_ROOT 权限并清理带 .perago-attempt.json marker 的目录。

publish fence 和 LakeFS merge 失败会让 attempt FAILED，不会生成 workspace output。cleanup 失败只写日志，不回滚已经完成的 target branch merge。publish 成功但 Conductor completion 未上报时，Perago 不补发旧 completion；由 Conductor timeout/fail/retry 处理。

Where To Look Next

需要核对	页面
Conductor input/output JSON shape	Input/Output Contract
generated TaskDef 字段、默认值和 None 省略规则	Conductor TaskDef
环境变量、.env 解析和配置错误	Environment Variables
result status 和 failure mapping	Failure Classification
worker JSONL 日志路径和排查入口	Runtime Logging
LakeFS download/stage/publish/cleanup 生命周期	LakeFS Runtime