{
  "id": "opencv/gpu-mat-upload-failed",
  "signature": "cv::error: (-217:Unknown error code 217) GpuMat::upload() failed: the input matrix is empty or has an unsupported type in function 'upload'",
  "signature_zh": "cv::error: (-217:未知错误码217) GpuMat::upload() 失败：输入矩阵为空或类型不受支持 在函数 'upload' 中",
  "regex": "cv::error: \\(-217:Unknown error code 217\\) GpuMat::upload\\(\\) failed: the input matrix is empty or has an unsupported type in function 'upload'",
  "domain": "opencv",
  "category": "type_error",
  "subcategory": null,
  "root_cause": "Attempting to upload an empty cv::Mat or a Mat with a data type not supported by CUDA (e.g., CV_8UC3) to a GpuMat.",
  "root_cause_type": "generic",
  "root_cause_zh": "尝试将空的cv::Mat或数据类型不受CUDA支持（例如CV_8UC3）的Mat上传到GpuMat。",
  "versions": [
    {
      "version": "4.5.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "4.6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "4.7.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "4.8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "4.9.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "cv::cuda::GpuMat::upload() only supports single-channel or 4-channel types (e.g., CV_8UC1, CV_8UC4, CV_32FC1); CV_8UC3 is not directly supported and must be split.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "An empty Mat can result from failed image loading or processing; the upload function does not handle empty inputs.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Convert the Mat to a supported type before upload. For CV_8UC3, split into three CV_8UC1 channels and upload each separately, or convert to CV_8UC4 using cvtColor with COLOR_BGR2BGRA. Example: cv::Mat bgra; cv::cvtColor(bgr, bgra, cv::COLOR_BGR2BGRA); cv::cuda::GpuMat gpuMat; gpuMat.upload(bgra);",
      "success_rate": 0.9,
      "how": "Convert the Mat to a supported type before upload. For CV_8UC3, split into three CV_8UC1 channels and upload each separately, or convert to CV_8UC4 using cvtColor with COLOR_BGR2BGRA. Example: cv::Mat bgra; cv::cvtColor(bgr, bgra, cv::COLOR_BGR2BGRA); cv::cuda::GpuMat gpuMat; gpuMat.upload(bgra);",
      "condition": "",
      "sources": []
    },
    {
      "action": "Always verify the Mat is not empty and has a supported type: if (mat.empty() || mat.type() != CV_8UC1 && mat.type() != CV_8UC4 && mat.type() != CV_32FC1) { /* handle error */ }",
      "success_rate": 0.85,
      "how": "Always verify the Mat is not empty and has a supported type: if (mat.empty() || mat.type() != CV_8UC1 && mat.type() != CV_8UC4 && mat.type() != CV_32FC1) { /* handle error */ }",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Convert the Mat to a supported type before upload. For CV_8UC3, split into three CV_8UC1 channels and upload each separately, or convert to CV_8UC4 using cvtColor with COLOR_BGR2BGRA. Example: cv::Mat bgra; cv::cvtColor(bgr, bgra, cv::COLOR_BGR2BGRA); cv::cuda::GpuMat gpuMat; gpuMat.upload(bgra);",
    "Always verify the Mat is not empty and has a supported type: if (mat.empty() || mat.type() != CV_8UC1 && mat.type() != CV_8UC4 && mat.type() != CV_32FC1) { /* handle error */ }"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://docs.opencv.org/4.x/d0/d3f/classcv_1_1cuda_1_1GpuMat.html#a7b8c5b9e6f9e8d0a1b2c3d4e5f6g7h8",
  "official_doc_section": null,
  "error_code": "-217",
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.88,
  "resolvable": "true",
  "first_seen": "2024-01-10",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}