Billionmail/BillionMail · error

failed to convert overview data: %v

Error message

failed to convert overview data: %v

What it means

Overview calls maillog_stat's Overview to get a statistics map, then converts it into res.Data with gconv.Struct. Any conversion failure — incompatible field types, unexpected map shape, nil input — is wrapped as 'failed to convert overview data'.

Source

Thrown at core/internal/controller/overview/overview_v1_overview.go:33

func (c *ControllerV1) Overview(ctx context.Context, req *v1.OverviewReq) (res *v1.OverviewRes, err error) {
	res = &v1.OverviewRes{}

	if req.EndTime == 0 {
		req.EndTime = time.Now().Unix()
	}

	if req.EndTime < req.StartTime {
		err = fmt.Errorf("start time must be greater or equal to end time")
		return
	}

	overview := maillog_stat.NewOverview()
	overviewMap := overview.Overview(req.CampaignId, req.Domain, req.StartTime, req.EndTime)

	err = gconv.Struct(overviewMap, &res.Data)

	if err != nil {
		err = fmt.Errorf("failed to convert overview data: %v", err)
		return
	}

	res.SetSuccess(public.LangCtx(ctx, "Success"))

	return
}

View on GitHub (pinned to fc36c76c05)

Solutions

1. Read the wrapped conversion error to identify the offending field
2. Update res.Data struct tags/types to match the service's output map keys
3. Handle nullable/NULL DB values with pointer or sql nullable types
4. Add a regression test that runs gconv.Struct against real service output

Example fix

// before
err = gconv.Struct(overviewMap, &res.Data)
// after
if overviewMap == nil { overviewMap = map[string]interface{}{} }
if err := gconv.Struct(overviewMap, &res.Data); err != nil {
    err = fmt.Errorf("failed to convert overview data: %v", err)
}

if (overviewMap == null) throw new Error('overview map is empty');

function isOverviewMap(x: unknown): x is Record<string, unknown> {
  return typeof x === 'object' && x !== null;
}

try {
  const data = await api.overview(params);
} catch (err) {
  if (String(err.message).startsWith('failed to convert overview data')) {
    // log wrapped cause and report schema mismatch
    console.error(err);
  }
}

When it happens

Trigger: The overview service returning a map whose keys/value types do not match res.Data's expected struct (e.g. string vs int for counts), or a nil/empty map where a populated one is required.

Common situations: Refactor changed the service's returned map keys; DB aggregates returning NULL or decimal types that don't fit int fields; API contract drift between deployed service and controller versions.

Related errors

• failed to convert overview data: %v
• Failed to add exception recipient: %w
• Failed to remove exception recipient: %w
• Failed to get exception recipient: %w
• Failed to query existing abnormal recipients: %w

AI-assisted analysis of Billionmail/BillionMail@fc36c76c05 (2026-09-05). Data as JSON: /api/errors/d56bbf604775b3ed. Report an issue: GitHub.