Tencent/WeKnora · error

failed to enqueue manual process task: %w

Error message

failed to enqueue manual process task: %w

What it means

Enqueueing the asynq manual:process task (default queue, 3 retries, 30m timeout) on the task broker failed after the payload was marshaled, meaning the async cleanup/re-index work was never scheduled; Redis/asynq connectivity or serialization issues are the usual causes.

Source

Thrown at internal/application/service/knowledge_create.go:1139

	payload := types.ManualProcessPayload{
		RequestId:       requestID,
		TenantID:        knowledge.TenantID,
		KnowledgeID:     knowledge.ID,
		KnowledgeBaseID: knowledge.KnowledgeBaseID,
		Content:         content,
		NeedCleanup:     needCleanup,
	}
	langfuse.InjectTracing(ctx, &payload)
	payloadBytes, err := json.Marshal(payload)
	if err != nil {
		return "", fmt.Errorf("failed to marshal manual process payload: %w", err)
	}

	task := asynq.NewTask(types.TypeManualProcess, payloadBytes,
		asynq.Queue(types.QueueDefault), asynq.MaxRetry(3), asynq.Timeout(30*time.Minute))
	info, err := s.task.Enqueue(task)
	if err != nil {
		return "", fmt.Errorf("failed to enqueue manual process task: %w", err)
	}
	logger.Infof(ctx, "Enqueued manual process task: knowledge_id=%s, asynq_id=%s", knowledge.ID, info.ID)
	return info.ID, nil
}

// markKnowledgeEnqueueFailed prevents a durable knowledge row from remaining
// indefinitely "pending" when its background processing task was never
// created. The API may still return the row so callers can retry it.
func (s *knowledgeService) markKnowledgeEnqueueFailed(ctx context.Context, knowledge *types.Knowledge) {
	if knowledge == nil {
		return
	}
	knowledge.ParseStatus = "failed"
	knowledge.ErrorMessage = "Failed to enqueue processing task"
	if err := s.repo.UpdateKnowledge(ctx, knowledge); err != nil {
		logger.Errorf(ctx, "Failed to mark knowledge as failed after enqueue error: %v", err)
	}
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check asynq/Redis broker connectivity
2. Verify task type registration on the worker side
3. Retry enqueueing or fall back to synchronous processing

When it happens

Trigger: Thrown at internal/application/service/knowledge_create.go:1139 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/6c1095a2eb3188f7. Report an issue: GitHub.