Troubleshooting Guide

Table of Contents

• Build Issues
  • "error: 'format' is not a member of 'std'"
  • "concept 'invocable' was not declared"
• CMake Configuration Issues
  • "Could not find package kcenon-common-system"
• vcpkg Integration Issues
  • "port name not recognized"
• Linker Issues
  • "undefined reference to kcenon::common::event_bus::publish"
• Runtime Issues
  • "service_container::resolve: type not registered"
  • "bad_result_access thrown from Result::value()"

Build Issues

"error: 'format' is not a member of 'std'"

Cause**: Your compiler is below the C++20 baseline required by common_system. std::format arrived in GCC 13, Clang 17, and MSVC 2022 — earlier versions will reject the headers.

Fix**: Upgrade the compiler, or on Linux install libstdc++-13-dev alongside GCC 13.

"concept 'invocable' was not declared"

Cause**: The <concepts> header isn't being found, or -std=c++20 isn't being passed to the compiler.

Fix**: In CMake, ensure CMAKE_CXX_STANDARD is set before the project declaration:

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
project(my_app)

CMake Configuration Issues

"Could not find package kcenon-common-system"

Cause**: CMake can't locate the installed package. Either it isn't installed, or CMAKE_PREFIX_PATH doesn't include the install location.

Fix**: Either install common_system to a system location (cmake --install build), or point your build at the install tree:

cmake -B build -DCMAKE_PREFIX_PATH=/opt/kcenon

For development, prefer FetchContent or add_subdirectory to pull common_system directly into your build.

vcpkg Integration Issues

"port name not recognized"

Cause**: vcpkg's registry doesn't know about common_system — you need to register the overlay.

Fix**: Add the overlay to vcpkg-configuration.json:

{
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/kcenon/vcpkg-registry",
      "reference": "main",
      "baseline": "...",
      "packages": ["kcenon-common-system"]
    }
  ]
}

Linker Issues

"undefined reference to kcenon::common::event_bus::publish"

Cause**: The application is including the headers but not linking the library target. Some patterns (event bus, circuit breaker) have out-of-line definitions.

Fix**: In your CMakeLists.txt:

target_link_libraries(my_app PRIVATE kcenon::common_system)

Do NOT just add the include path — the linker needs the target.

Runtime Issues

"service_container::resolve: type not registered"

Cause**: You're trying to resolve a service that nothing ever registered. Common causes: initialization order, register-after-resolve, or the wrong interface type.

Fix**: Ensure registration happens during startup, before the first resolve. Log or break at the registration point to confirm it actually runs:

auto& container = service_container::instance();
container.register_singleton<IClock, system_clock>();
assert(container.contains<IClock>());  // verify

"bad_result_access thrown from Result::value()"

Cause**: You called .value() on a Result that carries an error. The error details are in .error(), not .value().

Fix**: Check .is_ok() first, or use .value_or(default). See Tutorial: Result<T> Error Handling for the idiomatic pattern.