What causes "failed to insert alias: %v" in Billionmail/BillionMail?

Check the wrapped driver error: connection issues first (is Postgres up?), then SQL syntax/constraint messages

failed to insert alias: %v

Error message

failed to insert alias: %v

What it means

setCatchall wraps an INSERT into the `alias` table when the catchall alias row does not yet exist and must be created. The wrapped error is the raw GoFrame/PostgreSQL insert failure, annotated so callers of Add/Update know the catchall creation step failed.

Source

Thrown at core/internal/service/domains/domains.go:75

			_, err = g.DB().Model("alias").
				Where("address", address).
				Where("domain", domainName).
				Data(g.Map{"goto": catchall, "active": 1, "update_time": time.Now().Unix()}).
				Update()
			if err != nil {
				return fmt.Errorf("failed to update alias: %v", err)
			}
		} else {
			_, err = g.DB().Model("alias").Data(g.Map{
				"address":     address,
				"goto":        catchall,
				"domain":      domainName,
				"active":      1,
				"create_time": time.Now().Unix(),
				"update_time": time.Now().Unix(),
			}).Insert()
			if err != nil {
				return fmt.Errorf("failed to insert alias: %v", err)
			}
		}
	} else {
		// catchall is empty, disabled
		_, _ = g.DB().Model("alias").
			Where("address", address).
			Where("domain", domainName).
			Data(g.Map{"active": 0, "update_time": time.Now().Unix()}).
			Update()
	}
	return nil
}

func Add(ctx context.Context, domain *v1.Domain) error {
	domain.CreateTime = time.Now().Unix()
	domain.Active = 1

	_, err := g.DB().Model("domain").Ctx(ctx).Insert(domain)

View on GitHub (pinned to fc36c76c05)

Solutions

Check the wrapped driver error: connection issues first (is Postgres up?), then SQL syntax/constraint messages
Ensure a unique index on alias.address and that no conflicting row exists
Grant INSERT privilege on alias to the application DB user
Retry the domain Add/Update after the DB is healthy

Example fix

// before
_, err = g.DB().Model("alias").Data(g.Map{...}).Insert()
// after
_, err = g.DB().Model("alias").Data(g.Map{...}).Save() // upsert to tolerate existing row
if err != nil { return fmt.Errorf("failed to insert alias: %v", err) }

Defensive patterns

Strategy: validation

Validate before calling

dup, _ := g.DB().Model("alias").Where("address", address).Count()
if dup > 0 { return nil } // already exists, skip insert
if catchall == "" { return errors.New("catchall must be non-empty") }

Try / catch

_, err := g.DB().Model("alias").Data(g.Map{...}).Insert()
if err != nil {
    if strings.Contains(err.Error(), "duplicate key") { return g.DB().Model("alias").Where("address", address).Data(g.Map{"goto": catchall}).Update() }
    return fmt.Errorf("failed to insert alias: %v", err)
}

Prevention

Use Save()/upsert semantics instead of blind Insert
Validate domain names before composing the alias address
Grant INSERT/UPDATE on alias to the app DB role in deployment scripts
Add a unique constraint and handle it explicitly rather than letting inserts fail

When it happens

Trigger: domains.Add or domains.Update with a non-empty Catchall, when no alias row exists for the domain (count query returned 0) and the INSERT of (address, goto, domain, active, create_time, update_time) fails — DB unreachable, NOT NULL/unique violation, or permission denied on INSERT.

Common situations: First-time domain creation while Postgres is down; duplicate alias address violating a unique index; DB role missing INSERT privilege; malformed domain name producing an invalid address value.

Related errors

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