Introduction

This confusion comes from OpenCV's long transition from the old C API to the newer C++ API. Older machine-learning code often expects CvFileStorage*, while newer code uses cv::FileStorage, and the two are related historically but not interchangeable at the type level.

The Two APIs

OpenCV used to expose many C-style structs and functions such as:

• 'CvFileStorage*'
• 'cvOpenFileStorage'
• old CvStatModel-style machine-learning classes

Modern OpenCV code prefers C++ classes such as:

• 'cv::FileStorage'
• 'cv::ml::SVM'
• 'cv::Algorithm::load'

That means the right answer depends on which generation of the API your model code is using.

Legacy C-Style Example

If you are working with an older API that explicitly expects CvFileStorage*, then you need the old file-storage handle:

1#include <opencv2/core/core_c.h>
2
3int main() {
4    CvFileStorage* fs = cvOpenFileStorage("model.xml", 0, CV_STORAGE_READ);
5    if (!fs) {
6        return 1;
7    }
8
9    CvFileNode* root = cvGetRootFileNode(fs);
10    if (root) {
11        // Legacy APIs may read nodes from this storage handle.
12    }
13
14    cvReleaseFileStorage(&fs);
15    return 0;
16}

That style is still valid for maintaining old code, but it is not how new OpenCV code should usually be written.

Modern C++ Example

If you are using the newer machine-learning module, prefer cv::FileStorage or higher-level save and load calls:

1#include <opencv2/core.hpp>
2#include <opencv2/ml.hpp>
3
4int main() {
5    auto svm = cv::ml::SVM::create();
6    svm->setType(cv::ml::SVM::C_SVC);
7    svm->setKernel(cv::ml::SVM::LINEAR);
8
9    cv::FileStorage fs("model.yml", cv::FileStorage::WRITE);
10    if (!fs.isOpened()) {
11        return 1;
12    }
13
14    fs << "note" << "metadata written with cv::FileStorage";
15    fs.release();
16
17    svm->save("svm_model.yml");
18    auto loaded = cv::Algorithm::load<cv::ml::SVM>("svm_model.yml");
19    return loaded.empty() ? 1 : 0;
20}

This is the direction OpenCV has been moving toward for years: RAII-friendly C++ classes instead of raw C handles.

Why the Types Do Not Match

CvFileStorage* is a pointer to a legacy C struct. cv::FileStorage is a C++ class with constructors, methods, and automatic cleanup behavior. Even though both represent file-storage functionality, they are not substitute names for the same type.

So if a function signature says CvFileStorage*, you cannot pass a cv::FileStorage object directly and expect the compiler to adapt it.

That is a strong signal that your code path is using legacy OpenCV APIs.

Migration Strategy

If you are stuck on older ML classes, keep the old storage type for that boundary and isolate it. If you have the option to migrate, prefer modern cv::ml interfaces and Algorithm::load or save.

A good migration rule is:

• maintain old C API only where required
• write new code in the C++ API
• avoid mixing the two styles throughout the same module unless necessary

That keeps the compatibility surface small. It also makes later OpenCV upgrades much less painful because modern APIs tend to have clearer ownership and serialization paths.

Common Pitfalls

The biggest mistake is assuming the issue is just capitalization. It is not. CvFileStorage and cv::FileStorage come from different API layers.

Another mistake is trying to convert everything manually when OpenCV already provides higher-level load and save functions on modern model classes.

A third issue is mixing headers from old and new APIs without understanding which model classes you are actually using. If the type mismatch appears, inspect the function signature first and determine whether you are on a legacy or modern code path.

Summary

• 'CvFileStorage* belongs to OpenCV's legacy C API.'
• 'cv::FileStorage belongs to the modern C++ API.'
• They provide related functionality but are not interchangeable types.
• If the function expects CvFileStorage*, you are using a legacy API boundary.
• Prefer modern cv::ml classes and save or load methods for new OpenCV code.