enhance: classify segcore errors across producers and enforce classification end-to-end

.github/workflows/code-checker.yaml

@@ -60,7 +60,7 @@ jobs:
         env:
           OS_NAME: 'ubuntu22.04'
         run: |
-          ./build/builder.sh /bin/bash -c "git config --global --add safe.directory /go/src/github.com/milvus-io/milvus && make check-proto-product && make verifiers"
+          ./build/builder.sh /bin/bash -c "git config --global --add safe.directory /go/src/github.com/milvus-io/milvus && make check-proto-product && make check-segcore-codes-product && make verifiers"
       - name: Save Caches
         uses: ./.github/actions/cache-save
         if: github.event_name != 'pull_request'

.golangci.yml

@@ -10,6 +10,7 @@ linters:
     - decorder
     - depguard
     - durationcheck
+    - exhaustive
     - forbidigo
     - gocritic
     - gosec
@@ -21,6 +22,13 @@ linters:
     - unconvert
     - whitespace
   settings:
+    exhaustive:
+      # Opt-in: only switches annotated with `//exhaustive:enforce` are checked,
+      # so this does not flag the many intentional partial switches across the
+      # codebase. Used to guard the generated SegcoreCode classification switch
+      # (pkg/util/merr/segcore.go) so a new C++ error code cannot ship
+      # unclassified.
+      explicit-exhaustive-switch: true
     depguard:
       rules:
         main:

Makefile

@@ -229,6 +229,8 @@ static-check: getdeps
 	@source $(PWD)/scripts/setenv.sh && cd client && GO111MODULE=on GOFLAGS=-buildvcs=false $(INSTALL_PATH)/golangci-lint run --timeout=30m --config $(PWD)/client/.golangci.yml
 	@echo "Start check go_client e2e package"
 	@source $(PWD)/scripts/setenv.sh && cd tests/go_client && GO111MODULE=on GOFLAGS=-buildvcs=false $(INSTALL_PATH)/golangci-lint run --build-tags L0,L1,L2,test --timeout=30m --config $(PWD)/tests/go_client/.golangci.yml
+	@echo "Start check segcore error boundaries"
+	@$(PWD)/scripts/check_segcore_error_boundaries.sh
 
 verifiers: build-cpp getdeps cppcheck rustcheck fmt static-check
 
@@ -292,6 +294,18 @@ generated-proto: download-milvus-proto build-3rdparty get-proto-deps
 	@echo "Generate proto ..."
 	@(env bash $(PWD)/scripts/generate_proto.sh ${INSTALL_PATH})
 
+generate-segcore-codes:
+	@echo "Generating segcore error code list from milvus-common ..."
+	@(env bash $(PWD)/scripts/generate_segcore_codes.sh)
+
+# CI gate: regenerate the segcore code list and fail on drift, so a
+# milvus-common pin bump that adds an ErrorCode cannot ship without the
+# generated snapshot (and therefore the classForCode switch) catching up.
+# Mirrors check-proto-product.
+check-segcore-codes-product: generate-segcore-codes
+	@git diff --exit-code -- pkg/util/merr/segcore_codes_gen.go || \
+		(echo "segcore_codes_gen.go is out of date with milvus-common's EasyAssert.h; run 'make generate-segcore-codes' and classify any new code in classForCode" && exit 1)
+
 build-cpp: generated-proto plan-parser-lib
 	@echo "Building Milvus cpp library ..."
 	@(env bash $(PWD)/scripts/core_build.sh -t ${mode} -a ${use_asan} -n ${use_disk_index} -y ${use_dynamic_simd} ${AZURE_OPTION} -x ${index_engine} -f $(tantivy_features) -S ${use_svs})

docs/dev/error_handling_casebook.md

@@ -258,19 +258,32 @@ This is the *reverse* of Pattern 1: here the C++ side really is validating
 user input, so collapsing it into the system table would have been the
 misclassification.
 
-**segcore pass-through codes collapse on the wire.** Most C++ codes are
-deliberately projected to 2000 (`ErrSegcore`) on the wire, with the original
-code preserved in `Reason` as `segcoreCode=`. This includes C++ codes 2001 and
-2002; they do **not** map to the similarly numbered Go sentinels. The dedicated
-`segcoreCodeTable` mappings are: 2003 → `ErrSegcoreUnsupported` (wire 2001),
-2033 → `ErrSegcorePretendFinished` (wire 2002, control-flow signal), 2037 →
-`ErrSegcoreFollyOtherException`, 2038 → `ErrSegcoreFollyCancel`, 2039 →
-`ErrSegcoreOutOfRange`, 2040 → `ErrSegcoreGCPNativeError`, 2046 →
-`ErrCollectionSchemaVersionNotReady` (wire 110), and 2099 → `KnowhereError`.
-Codes 2037, 2040, and 2046 are retriable. Don't "improve" a call site by
-hand-picking a 20xx number — go through `merr.SegcoreError(code, msg)` and let
-the table decide retriability and projection. Guard tests:
-`pkg/util/merr/segcore_test.go` (`wire_code_projection`,
+**segcore codes pass through to the wire.** An in-band C++ code (2000-2099)
+now reaches the client as its ORIGINAL value: 2028 stays 2028, 2024 stays
+2024, and an in-band code added by a future C++ version passes through
+unchanged under the `ErrSegcore` family umbrella. Guardrails: an out-of-band
+(garbage) code still collapses to 2000; cross-family mappings keep their
+sentinel's wire code (2046 → `ErrCollectionSchemaVersionNotReady`, wire 110).
+Family identity for `errors.Is` is preserved via inner/Unwrap.
+
+Compatibility (changed in the pass-through PR): previously most codes were
+projected to wire 2000 with the real code buried in `Reason`; additionally the
+sentinels were renumbered to the C++ values they represent —
+`ErrSegcoreUnsupported` 2001 → **2003**, `ErrSegcorePretendFinished` 2002 →
+**2033** — because their old numbers squatted on C++ UnexpectedError /
+NotImplemented and would false-match under code-based `errors.Is`. An
+application matching wire codes 2000/2001/2002 must be updated: wire 2001 now
+means C++ `UnexpectedError` itself (an unclassified internal failure), wire
+2002 means C++ `NotImplemented`, and the Unsupported / pretend-finished
+signals arrive as 2003 / 2033.
+
+Retriability is unchanged by the wire projection: transient codes (2012-2015,
+2018, 2027, 2034, 2036-2037, 2040, 2043, 2045-2046, ...) are marked retriable
+by `classForCode`; input codes (2025/2026/2028/2031/2032/2042) are
+`InputError`. Don't "improve" a call site by hand-picking a 20xx number — go
+through `merr.SegcoreError(code, msg)` and let the table decide retriability
+and projection. Guard tests: `pkg/util/merr/segcore_test.go`
+(`wire_code_projection`, `named_sentinel_wire_transitions`,
 `TestSegcoreCodeTableCoverage`).
 
 ---

internal/core/src/clustering/KmeansClustering.cpp

@@ -105,10 +105,12 @@ KmeansClustering::FetchDataFiles(uint8_t* buf,
         fetched_file_size +=
             CopyFieldDatasToBuf(buf, expected_train_size, field_datas, offset);
     }
-    AssertInfo(fetched_file_size == expected_remote_file_size,
-               "file size inconsistent, expected: {}, actual: {}",
-               expected_remote_file_size,
-               fetched_file_size);
+    if (!(fetched_file_size == expected_remote_file_size)) {
+        ThrowInfo(ErrorCode::FileReadFailed,
+                  "file size inconsistent, expected: {}, actual: {}",
+                  expected_remote_file_size,
+                  fetched_file_size);
+    }
 }
 
 template <typename T>
@@ -128,10 +130,12 @@ KmeansClustering::FetchSegmentViaManifest(
     auto field_datas = file_manager_->CacheRawDataToMemory(config);
     int64_t fetched =
         CopyFieldDatasToBuf(buf, expected_train_size, field_datas, offset);
-    AssertInfo(fetched == expected_remote_file_size,
-               "file size inconsistent, expected: {}, actual: {}",
-               expected_remote_file_size,
-               fetched);
+    if (!(fetched == expected_remote_file_size)) {
+        ThrowInfo(ErrorCode::FileReadFailed,
+                  "file size inconsistent, expected: {}, actual: {}",
+                  expected_remote_file_size,
+                  fetched);
+    }
 }
 
 template <typename T>
@@ -381,7 +385,7 @@ KmeansClustering::StreamingAssignandUpload(
             dataset->SetIsOwner(true);
             auto res = cluster_node.Assign(*dataset);
             if (!res.has_value()) {
-                ThrowInfo(ErrorCode::UnexpectedError,
+                ThrowInfo(KnowhereStatusToErrorCode(res.error()),
                           fmt::format("failed to kmeans assign: {}: {}",
                                       KnowhereStatusString(res.error()),
                                       res.what()));
@@ -530,7 +534,7 @@ KmeansClustering::Run(const milvus::proto::clustering::AnalyzeInfo& config) {
     // return id mapping
     auto res = cluster_node.Train(*dataset, train_conf);
     if (!res.has_value()) {
-        ThrowInfo(ErrorCode::UnexpectedError,
+        ThrowInfo(KnowhereStatusToErrorCode(res.error()),
                   fmt::format("failed to kmeans train: {}: {}",
                               KnowhereStatusString(res.error()),
                               res.what()));
@@ -544,10 +548,10 @@ KmeansClustering::Run(const milvus::proto::clustering::AnalyzeInfo& config) {
 
     auto centroids_res = cluster_node.GetCentroids();
     if (!centroids_res.has_value()) {
-        ThrowInfo(ErrorCode::UnexpectedError,
+        ThrowInfo(KnowhereStatusToErrorCode(centroids_res.error()),
                   fmt::format("failed to get centroids: {}: {}",
-                              KnowhereStatusString(res.error()),
-                              res.what()));
+                              KnowhereStatusString(centroids_res.error()),
+                              centroids_res.what()));
     }
     // centroids owned by cluster_node
     centroids_res.value()->SetIsOwner(false);

internal/core/src/clustering/analyze_c.cpp

@@ -20,6 +20,7 @@
 #include "analyze_c.h"
 #include "bitset/common.h"
 #include "clustering/KmeansClustering.h"
+#include "common/CGoCatch.h"
 #include "common/EasyAssert.h"
 #include "common/Types.h"
 #include "fmt/core.h"
@@ -161,12 +162,8 @@ Analyze(CAnalyze* res_analyze,
         status.error_code = e.get_error_code();
         status.error_msg = strdup(e.what());
         return status;
-    } catch (std::exception& e) {
-        auto status = CStatus();
-        status.error_code = UnexpectedError;
-        status.error_msg = strdup(e.what());
-        return status;
     }
+    CGO_CATCH_AND_RETURN_CSTATUS
 }
 
 CStatus
@@ -181,9 +178,11 @@ DeleteAnalyze(CAnalyze analyze) {
         delete real_analyze;
         status.error_code = Success;
         status.error_msg = "";
-    } catch (std::exception& e) {
-        status.error_code = UnexpectedError;
-        status.error_msg = strdup(e.what());
+    } catch (const std::exception& e) {
+        status = milvus::FailureCStatus(&e);
+    } catch (...) {
+        status = milvus::FailureCStatus(milvus::UnexpectedError,
+                                        "unknown exception");
     }
     return status;
 }
@@ -219,9 +218,11 @@ GetAnalyzeResultMeta(CAnalyze analyze,
         }
         status.error_code = Success;
         status.error_msg = "";
-    } catch (std::exception& e) {
-        status.error_code = UnexpectedError;
-        status.error_msg = strdup(e.what());
+    } catch (const std::exception& e) {
+        status = milvus::FailureCStatus(&e);
+    } catch (...) {
+        status = milvus::FailureCStatus(milvus::UnexpectedError,
+                                        "unknown exception");
     }
     return status;
 }

internal/core/src/common/BloomFilter.h

@@ -22,6 +22,7 @@
 #include <stdexcept>
 #include "log/Log.h"
 #include "xxhash.h"  // from xxhash/xxhash
+#include "common/EasyAssert.h"
 
 namespace milvus {
 
@@ -119,8 +120,10 @@ class BlockedBloomFilter : public BloomFilter {
     explicit BlockedBloomFilter(const nlohmann::json& data) {
         if (!data.contains("bits") || !data.contains("num_bits") ||
             !data.contains("k")) {
-            throw std::runtime_error(
-                "Invalid JSON for BlockedBloomFilter: missing required fields");
+            ThrowInfo(ErrorCode::DataFormatBroken,
+                      "{}",
+                      std::string("Invalid JSON for BlockedBloomFilter: "
+                                  "missing required fields"));
         }
 
         bits_ = data["bits"].get<std::vector<uint64_t>>();
@@ -322,8 +325,10 @@ NewBloomFilterWithType(uint64_t capacity,
 inline BloomFilterPtr
 BloomFilterFromJson(const nlohmann::json& data) {
     if (!data.contains("type")) {
-        throw std::runtime_error(
-            "JSON data for bloom filter missing 'type' field");
+        ThrowInfo(
+            ErrorCode::DataFormatBroken,
+            "{}",
+            std::string("JSON data for bloom filter missing 'type' field"));
     }
 
     std::string type_str = data["type"].get<std::string>();
@@ -335,8 +340,10 @@ BloomFilterFromJson(const nlohmann::json& data) {
         case BFType::AlwaysTrue:
             return g_always_true_bf;
         default:
-            throw std::runtime_error("Unsupported bloom filter type: " +
-                                     type_str);
+            ThrowInfo(
+                ErrorCode::Unsupported,
+                "{}",
+                std::string("Unsupported bloom filter type: " + type_str));
     }
 }
 

internal/core/src/common/CGoCatch.h

@@ -0,0 +1,63 @@
+// Licensed to the LF AI & Data foundation under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <exception>
+#include <new>
+
+#include "common/EasyAssert.h"
+#include "log/Log.h"
+
+// Shared catch tail for every extern "C" entry point that returns a CStatus.
+//
+// Two reasons it must be uniform:
+//   1. FailureCStatus(&e) dynamic_casts to SegcoreError and keeps its typed
+//      error code; hand-writing `status.error_code = UnexpectedError` instead
+//      throws that code away and collapses every failure to 2001 at the cgo
+//      boundary, defeating the knowhere/storage code mapping upstream of it.
+//   2. catch (...) ensures a non-std::exception can never escape across the C
+//      ABI boundary, which would otherwise terminate the process.
+//   3. std::bad_alloc is pulled out ahead of std::exception: it is not a
+//      SegcoreError, so FailureCStatus would label an out-of-memory failure
+//      UnexpectedError(2001) -- permanent -- when it is in fact retriable.
+#define CGO_CATCH_AND_RETURN_CSTATUS                                        \
+    catch (const std::bad_alloc& e) {                                       \
+        return milvus::FailureCStatus(milvus::MemAllocateFailed, e.what()); \
+    }                                                                       \
+    catch (const std::exception& e) {                                       \
+        return milvus::FailureCStatus(&e);                                  \
+    }                                                                       \
+    catch (...) {                                                           \
+        return milvus::FailureCStatus(milvus::UnexpectedError,              \
+                                      "unknown exception");                 \
+    }
+
+// Catch tail for extern "C" entry points that CANNOT return a CStatus (void /
+// bool / pointer returns). An escaping exception would cross the C ABI and
+// terminate the process, so it must be swallowed here; log loudly so the
+// failure is observable, and let the macro user follow with a safe fallback
+// return value. `entry_name` identifies the boundary function in the log.
+#define CGO_CATCH_AND_LOG(entry_name)                               \
+    catch (const std::exception& e) {                               \
+        LOG_ERROR("exception swallowed at cgo boundary {}: {}",     \
+                  entry_name,                                       \
+                  e.what());                                        \
+    }                                                               \
+    catch (...) {                                                   \
+        LOG_ERROR("unknown exception swallowed at cgo boundary {}", \
+                  entry_name);                                      \
+    }

internal/core/src/common/ChunkTarget.cpp

@@ -72,10 +72,12 @@ MmapChunkTarget::release() {
         mmap_flag |= MAP_POPULATE;
     }
     auto m = mmap(nullptr, cap_, PROT_READ, mmap_flag, file.Descriptor(), 0);
-    AssertInfo(m != MAP_FAILED,
-               "failed to map: {}, map_size={}",
-               strerror(errno),
-               cap_);
+    if (m == MAP_FAILED) {
+        ThrowInfo(ErrorCode::MmapError,
+                  "failed to map: {}, map_size={}",
+                  strerror(errno),
+                  cap_);
+    }
     return static_cast<char*>(m);
 }
 

internal/core/src/common/ChunkTarget.h

@@ -94,10 +94,12 @@ class MemChunkTarget : public ChunkTarget {
             mmap_flag |= MAP_POPULATE;
         }
         auto m = mmap(nullptr, cap, PROT_READ | PROT_WRITE, mmap_flag, -1, 0);
-        AssertInfo(m != MAP_FAILED,
-                   "failed to map: {}, map_size={}",
-                   strerror(errno),
-                   size_);
+        if (m == MAP_FAILED) {
+            ThrowInfo(ErrorCode::MmapError,
+                      "failed to map: {}, map_size={}",
+                      strerror(errno),
+                      size_);
+        }
         data_ = reinterpret_cast<char*>(m);
     }
 

internal/core/src/common/ChunkWriter.cpp

@@ -34,6 +34,7 @@
 #include "simdjson/base.h"
 #include "simdjson/padded_string.h"
 #include "storage/FileWriter.h"
+#include "storage/StatusToErrorCode.h"
 
 namespace milvus {
 namespace {
@@ -938,8 +939,15 @@ arrow::ArrayVector
 read_single_column_batches(std::shared_ptr<arrow::RecordBatchReader> reader) {
     arrow::ArrayVector array_vec;
     for (const auto& batch : *reader) {
-        auto batch_data = batch.ValueOrDie();
-        array_vec.push_back(batch_data->column(0));
+        // A failed read (corrupt file, IO error) surfaces here as an error
+        // Result; ValueOrDie would abort the process instead of throwing a
+        // classified error.
+        if (!batch.ok()) {
+            ThrowInfo(storage::ArrowStatusToErrorCode(batch.status()),
+                      "failed to read record batch: {}",
+                      batch.status().ToString());
+        }
+        array_vec.push_back(batch.ValueUnsafe()->column(0));
     }
     return array_vec;
 }