What causes "insertBoard error occurred while updating existing board %s: %w" in mattermost-community/focalboard?

insertBoard error occurred while updating existing board %s:

Error message

insertBoard error occurred while updating existing board %s: %w

What it means

When a board with the same ID already exists, insertBoard updates the existing row instead of inserting; if that UPDATE Exec fails, this error is returned (the failure is also logged server-side with the board ID). It wraps the raw driver error, so the real cause (constraint violation, lock timeout, connection loss) is in the wrapped err.

Source

Thrown at server/services/store/sqlstore/board.go:380

			Where(sq.Eq{"id": board.ID}).
			Set("modified_by", board.ModifiedBy).
			Set("type", board.Type).
			Set("channel_id", board.ChannelID).
			Set("minimum_role", board.MinimumRole).
			Set("title", board.Title).
			Set("description", board.Description).
			Set("icon", board.Icon).
			Set("show_description", board.ShowDescription).
			Set("is_template", board.IsTemplate).
			Set("template_version", board.TemplateVersion).
			Set("properties", propertiesBytes).
			Set("card_properties", cardPropertiesBytes).
			Set("update_at", board.UpdateAt).
			Set("delete_at", board.DeleteAt)

		if _, err := query.Exec(); err != nil {
			s.logger.Error(`InsertBoard error occurred while updating existing board`, mlog.String("boardID", board.ID), mlog.Err(err))
			return nil, fmt.Errorf("insertBoard error occurred while updating existing board %s: %w", board.ID, err)
		}
	} else {
		board.CreatedBy = userID
		board.CreateAt = now
		insertQueryValues["created_by"] = board.CreatedBy
		insertQueryValues["create_at"] = board.CreateAt

		query := insertQuery.SetMap(insertQueryValues).Into(s.tablePrefix + "boards")
		if _, err := query.Exec(); err != nil {
			return nil, fmt.Errorf("insertBoard error occurred while inserting board %s: %w", board.ID, err)
		}
	}

	// writing board history
	query := insertQuery.SetMap(insertQueryValues).Into(s.tablePrefix + "boards_history")
	if _, err := query.Exec(); err != nil {
		s.logger.Error("failed to insert board history", mlog.String("board_id", board.ID), mlog.Err(err))
		return nil, fmt.Errorf("failed to insert board %s history: %w", board.ID, err)

View on GitHub (pinned to a84bbb65e3)

Solutions

Check server logs for the paired 'InsertBoard error occurred while updating existing board' entry with the driver error detail
Inspect the wrapped err: lock/timeout issues → reduce concurrency or add retries; constraint issues → fix the payload
Verify card_properties bytes are valid JSON within DB column limits
Ensure the DB connection pool settings match your load (max open/idle connections)

Example fix

// before
insertBoard(board) // retries not configured, fails under lock contention
// after
for i := 0; i < 3; i++ {
    _, err := insertBoard(board)
    if err == nil || !isDeadlock(err) {
        break
    }
    time.Sleep(time.Duration(1<<i) * 100 * time.Millisecond)
}

Defensive patterns

Strategy: retry

Validate before calling

func isRetryableDBError(err error) bool {
    if err == nil { return false }
    s := err.Error()
    return strings.Contains(s, "Deadlock") || strings.Contains(s, "Lock wait timeout") || strings.Contains(s, "connection")
}

Try / catch

board, err := store.InsertBoard(board, userID)
if err != nil && strings.Contains(err.Error(), "error occurred while updating existing board") {
    if isRetryableDBError(err) {
        board, err = store.InsertBoard(board, userID) // safe: same board ID, idempotent update
    }
}

Prevention

Limit concurrent writes to the same board to reduce lock contention
Keep card_properties JSON within column size limits
Match DB pool sizing to workload to avoid lock pile-ups
Run MySQL in a mode compatible with the server's expected data types

When it happens

Trigger: InsertBoard/patchBoard/createBoardsAndBlocks/insertBoardWithAdmin hitting the update path where a board with board.ID exists, and the UPDATE fails — e.g. deadlocks, lock waits, constraint failures on card_properties JSON, or connection drops.

Common situations: Concurrent edits causing row lock contention; oversized/invalid card_properties data exceeding DB limits; connection pool exhaustion under load; MySQL strict-mode rejecting data types.

Related errors

AI-assisted analysis of mattermost-community/focalboard@a84bbb65e3 (2026-08-30). Data as JSON: /api/errors/961e109fb438f9b0. Report an issue: GitHub.