{"record":{"id":"df0dc6e524d1b63c","repo":"vxcontrol/pentagi","slug":"failed-to-prepare-primary-agent-chain-for-subtask","errorCode":null,"errorMessage":"failed to prepare primary agent chain for subtask %d: %w","messagePattern":"failed to prepare primary agent chain for subtask (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/controller/subtask.go","lineNumber":62,"sourceCode":"\tupdater    TaskUpdater\n\tcompleted  bool\n\twaiting    bool\n}\n\nfunc NewSubtaskWorker(\n\tctx context.Context,\n\ttaskCtx *TaskContext,\n\tid int64,\n\ttitle,\n\tdescription string,\n\tupdater TaskUpdater,\n) (SubtaskWorker, error) {\n\tctx, span := obs.Observer.NewSpan(ctx, obs.SpanKindInternal, \"controller.NewSubtaskWorker\")\n\tdefer span.End()\n\n\tmsgChainID, err := taskCtx.Provider.PrepareAgentChain(ctx, taskCtx.TaskID, id)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to prepare primary agent chain for subtask %d: %w\", id, err)\n\t}\n\n\treturn &subtaskWorker{\n\t\tmx: &sync.RWMutex{},\n\t\tsubtaskCtx: &SubtaskContext{\n\t\t\tMsgChainID:         msgChainID,\n\t\t\tSubtaskID:          id,\n\t\t\tSubtaskTitle:       title,\n\t\t\tSubtaskDescription: description,\n\t\t\tTaskContext:        *taskCtx,\n\t\t},\n\t\tupdater:   updater,\n\t\tcompleted: false,\n\t\twaiting:   false,\n\t}, nil\n}\n\nfunc LoadSubtaskWorker(","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/controller/subtask.go#L44-L80","documentation":"NewSubtaskWorker calls Provider.PrepareAgentChain to create the primary LLM message chain for a subtask and wraps any failure with the subtask ID. Failures originate in the provider layer: LLM provider misconfiguration, unavailability, or chain persistence errors in the database.","triggerScenarios":"PopSubtask dequeues a subtask and calls NewSubtaskWorker while PrepareAgentChain fails — e.g. no LLM provider configured/healthy, provider API key invalid, or the DB insert of the message chain fails.","commonSituations":"Missing or expired provider API keys in .env; all configured providers rate-limited or down; database connectivity issues during chain creation; provider type not registered/whitelisted after a config change.","solutions":["Inspect the wrapped cause (%w) to see whether the failure is provider-side or database-side.","Verify at least one LLM provider is configured with valid credentials in .env / provider settings.","Test provider reachability (API key, base URL, network egress) with a minimal request.","Check DB health and that message-chain tables/migrations are intact.","Retry the subtask; chain preparation may succeed once a transient provider outage ends."],"exampleFix":"// before\nsubtaskWorker, err := controller.NewSubtaskWorker(ctx, taskCtx, id)\nif err != nil {\n    log.Fatal(err)\n}\n// after\nsubtaskWorker, err := controller.NewSubtaskWorker(ctx, taskCtx, id)\nif err != nil {\n    log.Warn(\"chain prep failed, requeueing subtask\", \"id\", id, \"err\", err)\n    queue.Requeue(id) // retry later instead of crashing\n    return\n}","handlingStrategy":"retry","validationCode":"// preflight: confirm a provider is configured and reachable\nif taskCtx.Provider == nil {\n    return fmt.Errorf(\"no LLM provider configured\")\n}\nif err := taskCtx.Provider.HealthCheck(ctx); err != nil {\n    return fmt.Errorf(\"provider unhealthy: %w\", err)\n}","typeGuard":"func IsChainPrepError(err error) (subtaskID int64, ok bool) {\n    return subtaskID, strings.Contains(err.Error(), \"failed to prepare primary agent chain\")\n}","tryCatchPattern":"worker, err := controller.NewSubtaskWorker(ctx, taskCtx, subtaskID)\nif err != nil {\n    log.Warn(\"prepare chain failed\", \"subtask\", subtaskID, \"err\", err)\n    if retryable(err) {\n        queue.RequeueAfter(subtaskID, backoff)\n        return nil\n    }\n    return err\n}","preventionTips":["Configure and validate at least one LLM provider key at startup, not at first use.","Add a provider health/readiness check before processing the subtask queue.","Retry transient provider failures with exponential backoff.","Verify DB connectivity before spawning subtask workers."],"tags":["llm-provider","agent-chain","initialization"],"backgroundTag":"llm-provider-unavailable","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}