# cv::error: (-217:Unknown error code 217) GpuMat::upload() failed: the input matrix is empty or has an unsupported type in function 'upload'

- **ID:** `opencv/gpu-mat-upload-failed`
- **Domain:** opencv
- **Category:** type_error
- **Error Code:** `-217`
- **Verification:** ai_generated
- **Fix Rate:** 88%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 4.5.0 | active | — | — |
| 4.6.0 | active | — | — |
| 4.7.0 | active | — | — |
| 4.8.0 | active | — | — |
| 4.9.0 | active | — | — |

## Workarounds

1. **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);** (90% success)
   ```
   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);
   ```
2. **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 */ }** (85% success)
   ```
   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 */ }
   ```

## Dead Ends

- **** — 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. (90% fail)
- **** — An empty Mat can result from failed image loading or processing; the upload function does not handle empty inputs. (70% fail)