Tencent/WeKnora · error

model download failed

Error message

model download failed

What it means

When the fetched model's status is ModelStatusDownloadFailed, GetModelByID returns errors.New("model download failed") because the model was provisioned but its download errored out and it can never serve requests in that state. Unlike the downloading case, this is a persistent failure that requires intervention: the download must be re-triggered.

Source

Thrown at internal/application/service/model.go:199

		logger.Error(ctx, "Model not found")
		return nil, ErrModelNotFound
	}

	logger.Infof(ctx, "Model found, name: %s, status: %s", model.Name, model.Status)

	// Check model status
	if model.Status == types.ModelStatusActive {
		return model, nil
	}

	if model.Status == types.ModelStatusDownloading {
		logger.Warn(ctx, "Model is currently downloading")
		return nil, errors.New("model is currently downloading")
	}

	if model.Status == types.ModelStatusDownloadFailed {
		logger.Error(ctx, "Model download failed")
		return nil, errors.New("model download failed")
	}

	logger.Error(ctx, "Model status is abnormal")
	return nil, errors.New("abnormal model status")
}

// ListModels returns all models belonging to the tenant
func (s *modelService) ListModels(ctx context.Context) ([]*types.Model, error) {
	logger.Info(ctx, "Start listing models")

	tenantID := types.MustTenantIDFromContext(ctx)
	logger.Infof(ctx, "Listing models for tenant ID: %d", tenantID)

	// List models from repository with no additional filters
	models, err := s.repo.List(ctx, tenantID, "", "")
	if err != nil {
		logger.ErrorWithFields(ctx, err, map[string]interface{}{
			"tenant_id": tenantID,

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the model manager/download worker logs for the root-cause error (network, 404, disk space) at the time the download failed.
2. Fix the underlying cause (network access, free disk space, correct model source URL/credentials) and re-trigger the model download to move it back to downloading/active.
3. Delete and re-create (re-register) the model entry if the download job cannot be resumed, then wait for it to reach active status.
4. Add monitoring/alerting on ModelStatusDownloadFailed so failures are caught and retried automatically rather than surfacing as request errors.

Example fix

// before
model, err := modelService.GetRerankModel(ctx, modelID) // fails: download failed
// after
if err := modelManager.RetryDownload(ctx, modelID); err != nil { return nil, err }
if err := modelManager.WaitUntilActive(ctx, modelID, 5*time.Minute); err != nil { return nil, err }
model, err := modelService.GetRerankModel(ctx, modelID)

m, err := svc.GetModelByID(ctx, modelID)
if err == nil && m.Status == types.ModelStatusDownloadFailed {
    // do not call; repair/re-download first
}

func isDownloadFailed(m *types.Model) bool { return m != nil && m.Status == types.ModelStatusDownloadFailed }

model, err := svc.GetModelByID(ctx, modelID)
if err != nil {
    if strings.Contains(err.Error(), "download failed") {
        return nil, fmt.Errorf("model %s is broken; re-trigger its download", modelID)
    }
    return nil, err
}

When it happens

Trigger: Calling GetModelByID/GetEmbeddingModel/GetRerankModel for a model whose persisted status is types.ModelStatusDownloadFailed — e.g. after a network failure, disk-full condition, or crash during model download.

Common situations: Offline/air-gapped deployments where the model artifact URL is unreachable; transient network outages during first provisioning; insufficient disk space on the worker; proxy/firewall blocking the model registry host; the model source URL changed or was removed upstream.

Related errors

• model is currently downloading
• model ID cannot be empty
• abnormal model status
• unknown credential field:
• model is not active

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