Troubleshooting

Build Fails with C++20 Errors

Aspose.PDF FOSS for C++ requires a C++20 compiler — clang 16+, gcc 13+, or MSVC 2022 17.5+. If your build fails with errors such as “designated initializers only allowed in C++20” or “concepts require ‘-std=c++20’”, the consuming project is not compiling with the C++20 standard enabled.

Set the standard explicitly before adding the library as a subdirectory:

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

On the command line this corresponds to -std=c++20 (clang/gcc) or /std:c++20 (MSVC).

CMake Configuration Fails — Version Too Old

The project requires CMake 3.22 or later. Running an older CMake produces an error similar to:

CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
  CMake 3.22 or higher is required.  You are running version 3.16.3

Check your installed version and upgrade rather than editing the vendored CMakeLists.txt:

cmake --version

Install a current release from cmake.org or your package manager — the minimum version reflects generator and language features the build actually uses, not an arbitrary floor.

FetchContent Fails to Download the Repository

If you vendor the library with FetchContent instead of a manual add_subdirectory, configure-time failures are usually a network problem rather than a CMake problem:

include(FetchContent)
FetchContent_Declare(
    aspose_pdf_foss
    GIT_REPOSITORY https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp.git
    GIT_TAG        main
)
FetchContent_MakeAvailable(aspose_pdf_foss)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

FetchContent_MakeAvailable runs git clone during CMake configuration. Behind a corporate proxy or firewall, or on an air-gapped CI runner, this fails with Failed to clone repository. To fix it:

Set HTTPS_PROXY/HTTP_PROXY for the CMake configure step, or
Pre-clone the repository once and point FETCHCONTENT_SOURCE_DIR_ASPOSE_PDF_FOSS at the local checkout so FetchContent reuses it instead of fetching over the network, or
Vendor the source directly and use add_subdirectory(), which has no network dependency at configure time.

Undefined Reference / Unresolved External Symbol at Link Time

Compilation succeeds but linking fails with undefined reference to Aspose::Pdf::Document::... (gcc/clang) or an unresolved external symbol error (MSVC). This is almost always one of two causes:

Missing link step — target_link_libraries(your_app PRIVATE aspose_pdf_foss) is missing or misspelled. add_subdirectory() alone only makes the headers visible; it does not link the static library.
Runtime library / build-type mismatch on MSVC — linking a Release-built aspose_pdf_foss.lib into a Debug executable (or vice versa) mixes incompatible C runtime libraries and fails with LNK2038 mismatches. Build the library and your application with the same CMAKE_BUILD_TYPE (or the same /MD//MDd runtime library setting).

XMP Metadata Type Checks Always Return False

XmpValue — the value type returned from Document.Metadata() entries — exposes type-checking helpers IsDateTime(), IsField(), IsNamedValue(), IsRaw(), IsNamedValues(), and IsStructure(). In the current release these six methods are stubs that unconditionally return false, so code that branches on them to distinguish XMP value kinds always takes the “false” path.

Use the implemented checks instead — IsString(), IsInteger(), IsDouble(), IsArray() — or call the matching accessor (ToStringValue(), ToInteger(), ToDouble(), ToArray()) directly when the value’s kind is already known from context. A small number of low-level internal types (BitmapInfo’s default constructor, and the internal Encoding and Value types used by the PDF object model) also contain stub bodies that are not exercised by typical document-processing code.