Troubleshooting Guide

About 1819 wordsAbout 6 min

2025-12-22

Even experienced developers encounter issues with Conan. This guide helps you quickly identify and fix the most common problems, from dependency conflicts to build failures.

Quick Diagnosis

Start Here - Basic Diagnostics

# 1. Check Conan version and configuration
conan --version
conan profile detect --force

# 2. Check system information
conan profile show

# 3. Clear cache and start fresh (nuclear option)
conan cache clean "*"

# 4. Verbose output for debugging
conan install . --verbose --build=missing

Debug Output Levels

# Basic output
conan install .

# Verbose output (more details)
conan install . --verbose

# Debug output (all details)
conan install . --debug

# Trace output (maximum details)
conan install . --trace

Installation and Setup Issues

Problem: "conan: command not found"

Symptoms:

bash: conan: command not found

Solutions:

# Check if Conan is installed
which conan

# If not found, reinstall
pip install conan

# Or check Python path
python3 -c "import conan; print(conan.__file__)"

# Add to PATH (Linux/macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell
$env:PATH += ";$env:USERPROFILE\.local\bin"

Problem: "Python version not supported"

Symptoms:

ERROR: Conan 2.X requires Python 3.7 or higher. Current version: 2.7.x

Solutions:

# Check Python version
python3 --version

# Install Python 3.7+ (Ubuntu/Debian)
sudo apt update
sudo apt install python3 python3-pip

# Install Python 3.7+ (macOS)
brew install python3

# Install Python 3.7+ (Windows)
# Download from python.org or use winget
winget install Python.Python.3.11

# Use specific Python version
python3 -m pip install conan

Problem: "Compiler not detected"

Symptoms:

ERROR: Unable to detect compiler

Solutions:

# Install C++ compiler (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential

# Install C++ compiler (macOS)
xcode-select --install

# Install C++ compiler (Windows)
# Install Visual Studio with "Desktop development with C++"

# Verify compiler installation
gcc --version          # Linux/macOS
cl.exe                 # Windows (in Developer Command Prompt)

# Force profile detection
conan profile detect --force

Dependency and Package Issues

Problem: "Package not found"

Symptoms:

ERROR: Package 'mypackage/1.0.0@user/channel' not found

Solutions:

# 1. Check if package exists
conan search mypackage --remote=conancenter

# 2. Check package name and version
conan search "mypackage*" --remote=conancenter

# 3. Check if remote is accessible
conan ping conancenter

# 4. Check if remote is enabled
conan remote list

# 5. Enable disabled remotes
conan remote enable conancenter

# 6. Check package reference format
# Correct: mypackage/1.0.0@user/channel
# Wrong: mypackage@1.0.0@user/channel

Problem: "Version conflict in dependencies"

Symptoms:

ERROR: Version conflict detected:
  - myapp/1.0.0 requires 'openssl/3.0.8'
  - myapp/1.0.0 requires 'openssl/1.1.1'

Solutions:

# Solution 1: Force a specific version
class MyAppConan(ConanFile):
    requires = (
        "package-a/1.0.0",
        "package-b/2.0.0",
        ("openssl/3.0.8", "override"),  # Force OpenSSL 3.0
    )

# Solution 2: Use compatible version ranges
class MyAppConan(ConanFile):
    requires = (
        "openssl/[>=3.0.0 <4.0.0]",  # Allow any 3.x version
    )

# Solution 3: Remove conflicting dependencies
class MyAppConan(ConanFile):
    def configure(self):
        # Remove transitive dependency
        if self.dependencies.get("openssl"):
            self.dependencies["openssl"].requires.clear()

Problem: "Dependency resolution failed"

Symptoms:

ERROR: Unable to resolve dependencies for myapp/1.0.0

Solutions:

# 1. Check dependency graph
conan install . --print=graph

# 2. Build missing dependencies
conan install . --build=missing

# 3. Build all dependencies from source
conan install . --build=outdated

# 4. Check for unavailable packages
conan install . --build=missing --build=outdated --verbose

# 5. Clear cache and retry
conan cache clean "*"
conan install . --build=missing

Build and Compilation Issues

Problem: "CMake not found"

Symptoms:

ERROR: CMake was not found in PATH

Solutions:

# Install CMake (Ubuntu/Debian)
sudo apt update
sudo apt install cmake

# Install CMake (macOS)
brew install cmake

# Install CMake (Windows)
# Download from cmake.org or use winget
winget install Kitware.CMake

# Or install via Conan
conan install . --build=missing
# Conan will download and use cmake if specified in tool_requires

# Verify installation
cmake --version

Problem: "Compiler version mismatch"

Symptoms:

ERROR: Package was built with different compiler version

Solutions:

# 1. Check current compiler
gcc --version
clang++ --version
cl.exe

# 2. Update profile to match compiler
conan profile detect --force

# 3. Check profile settings
conan profile show default

# 4. Update compiler version in profile
conan profile update settings.compiler.version=11 default

# 5. Rebuild package with correct compiler
conan install . --build=missing --profile=default

Problem: "Linker errors"

Symptoms:

undefined reference to `fmt::print'
/usr/bin/ld: cannot find -lfmt

Solutions:

# Solution 1: Fix CMakeLists.txt
# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(MyApp)

# Let Conan handle everything
find_package(fmt REQUIRED)
target_link_libraries(myapp PRIVATE fmt::fmt)

# Solution 2: Check package information
conan show fmt/10.0.0

# Solution 3: Verify include paths
conan install . --build=missing
cat build/Conan_toolchain.cmake | grep FMT

Problem: "Include file not found"

Symptoms:

fatal error: fmt/core.h: No such file or directory

Solutions:

# Solution 1: Verify package provides headers
# conanfile.py
class MyProjectConan(ConanFile):
    requires = "fmt/10.0.0"

    def package_info(self):
        # Check that headers are available
        fmt_libs = self.deps_cpp_info["fmt"].libs
        fmt_includes = self.deps_cpp_info["fmt"].include_paths
        print(f"fmt include paths: {fmt_includes}")

# Solution 2: Check CMake configuration
# CMakeLists.txt
find_package(fmt REQUIRED)
# This should set:
# - FMT_INCLUDE_DIRS
# - FMT_LIBRARIES

# Solution 3: Force rebuild
conan install . --build=fmt

Profile and Configuration Issues

Problem: "Profile not found"

Symptoms:

ERROR: Profile 'myprofile' not found

Solutions:

# 1. List available profiles
conan profile list

# 2. Create missing profile
conan profile new myprofile --detect

# 3. Use default profile instead
conan install . --profile=default

# 4. Create profile from file
conan profile new myprofile --file=myprofile.txt

# 5. Check profile file location
ls ~/.conan2/profiles/

Problem: "Invalid profile settings"

Symptoms:

ERROR: Invalid profile setting: compiler.version=invalid

Solutions:

# 1. Check valid settings values
conan profile show default

# 2. Update with valid values
conan profile update settings.compiler.version=11 default

# 3. Reset profile
conan profile detect --force

# 4. Validate profile
conan profile show myprofile

Problem: "Cross-compilation not working"

Symptoms:

ERROR: Build host configuration different from target

Solutions:

# Solution 1: Use proper cross-compilation profile
# cross-arm.profile
[settings]
os=Linux
arch=armv8
compiler=gcc
compiler.version=11
compiler.libcxx=libstdc++11
compiler.cppstd=17
build_type=Release

[env]
CC=arm-linux-gnueabihf-gcc
CXX=arm-linux-gnueabihf-g++

[conf]
tools.build:cflags=["-march=armv8-a"]
tools.build:cxxflags=["-march=armv8-a"]

# Solution 2: Use Conan cross-compilation features
# conanfile.py
class CrossCompileConan(ConanFile):
    settings = "os", "compiler", "build_type", "arch"

    def generate(self):
        tc = CMakeToolchain(self)
        tc.cache_variables["CMAKE_SYSTEM_NAME"] = "Linux"
        tc.cache_variables["CMAKE_SYSTEM_PROCESSOR"] = "arm"
        tc.cache_variables["CMAKE_C_COMPILER"] = "arm-linux-gnueabihf-gcc"
        tc.cache_variables["CMAKE_CXX_COMPILER"] = "arm-linux-gnueabihf-g++"
        tc.generate()

Remote and Authentication Issues

Problem: "Remote not accessible"

Symptoms:

ERROR: Unable to connect to remote 'myremote'

Solutions:

# 1. Check remote connectivity
conan ping myremote

# 2. Test with basic connection
curl -I https://myremote.com/conan/v1/

# 3. Check remote configuration
conan remote list

# 4. Re-add remote
conan remote remove myremote
conan remote add myremote https://myremote.com/conan/v1/

# 5. Disable SSL verification (development only)
conan remote add myremote http://insecure-server.com --insecure

Problem: "Authentication failed"

Symptoms:

ERROR: Unauthorized: Wrong username or password

Solutions:

# 1. Check authentication
conan remote auth myremote

# 2. Use environment variables
export CONAN_USERNAME=your_username
export CONAN_PASSWORD=your_password
conan install . --remote=myremote

# 3. Use API tokens instead of passwords
conan remote auth myremote --username=your_username --password=your_api_token

# 4. Clear authentication cache
conan user --clean

# 5. Re-authenticate
conan remote auth myremote --username=your_username

Problem: "SSL certificate verification failed"

Symptoms:

ERROR: SSL: CERTIFICATE_VERIFY_FAILED

Solutions:

# Solution 1: Update CA certificates
# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates

# macOS
/Applications/Python\ 3.x/Install\ Certificates.command

# Solution 2: Use correct CA bundle
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
export SSL_CERT_FILE=/path/to/ca-bundle.crt

# Solution 3: Disable verification (development only)
conan remote add myremote https://server.com --verify-ssl=false

# Solution 4: Add custom CA certificate
export REQUESTS_CA_BUNDLE=/path/to/custom-ca.pem

Cache and Storage Issues

Problem: "Disk space full"

Symptoms:

ERROR: No space left on device

Solutions:

# 1. Check cache size
du -sh ~/.conan2/

# 2. Clean cache
conan cache clean "*"

# 3. Remove specific packages
conan cache clean "mypackage/*"

# 4. Move cache to different location
export CONAN_USER_HOME=/path/to/larger/disk/.conan2

# 5. Configure cache limits
[conf]
# Limit cache size (if supported)
tools.cmake.cmake_layout:max_cache_size=10GB

Problem: "Cache corruption"

Symptoms:

ERROR: Package integrity check failed

Solutions:

# 1. Clear specific package
conan cache clean "mypackage/1.0.0@user/channel"

# 2. Clear entire cache
conan cache clean "*"

# 3. Remove cache directory
rm -rf ~/.conan2/

# 4. Reinstall Conan
pip install --upgrade conan

# 5. Re-detect profile
conan profile detect --force

Problem: "Slow downloads"

Symptoms:

Package downloads are very slow

Solutions:

# 1. Check network connectivity
ping center.conan.io

# 2. Use different remote
conan remote disable conancenter
conan remote add conancenter-mirror https://conan.bintray.com

# 3. Configure concurrent downloads
conan config set general.parallel_download=8

# 4. Use binary cache
export CONAN_USER_HOME=/fast/ssd/.conan2

# 5. Download packages manually
conan download fmt/10.0.0 --remote=conancenter

CMake Integration Issues

Problem: "CMake can't find dependencies"

Symptoms:

CMake Error: Could not find fmt

Solutions:

# Solution 1: Use Conan-generated CMake files
# conanfile.py
def generate(self):
    tc = CMakeToolchain(self)
    tc.generate()

    deps = CMakeDeps(self)
    deps.generate()

# CMakeLists.txt
# Load Conan-generated files
if(EXISTS ${CMAKE_BINARY_DIR}/conan/conan_toolchain.cmake)
    include(${CMAKE_BINARY_DIR}/conan/conan_toolchain.cmake)
endif()

# Use Conan dependencies
find_package(fmt REQUIRED)
target_link_libraries(myapp PRIVATE fmt::fmt)

# Solution 2: Check generated files
ls build/conan/
# Should contain: conan_toolchain.cmake, fmt-config.cmake, etc.

# Solution 3: Force regeneration
rm -rf build/
conan install . --build=missing

Problem: "Multiple CMake configurations"

Symptoms:

CMake Error: Found package 'fmt' but it was not a config package

Solutions:

# Solution 1: Use CMakeDeps generator
# conanfile.py
def generate(self):
    deps = CMakeDeps(self)
    deps.generate()

# NOT generators = ["cmake"]  # Old approach
# Use generators = ["CMakeDeps", "CMakeToolchain"]

# Solution 2: Check generated config files
find build/conan/ -name "*-config.cmake"
# Should find: fmt-config.cmake, spdlog-config.cmake, etc.

# Solution 3: Update to modern CMake
cmake_minimum_required(VERSION 3.15)
project(MyApp)

# Use modern CMake approach
find_package(fmt REQUIRED)

Debugging Advanced Issues

Enable Maximum Debug Output

# Enable all debugging features
export CONAN_VERBOSE_TRACEBACK=1
export CONAN_PYLINTRC=
export CONAN_PRINT_RUN_COMMANDS=1
export CONAN_LOG_RUN_TO_FILE=1

# Run with maximum verbosity
conan install . --verbose --debug --trace > debug.log 2>&1

Log Analysis

# Check Conan logs
ls ~/.conan2/logs/

# Analyze trace output
grep ERROR debug.log
grep "ERROR:" debug.log

# Check specific operations
grep "conan install" debug.log

Environment Investigation

# Check environment variables
env | grep CONAN

# Check paths
echo $PATH
echo $HOME

# Check Conan configuration
conan config get

# Check cache location
conan cache path

Common Error Messages and Solutions

Error Message	Likely Cause	Quick Fix
`command not found`	Conan not installed	`pip install conan`
`Package not found`	Wrong package name or remote	`conan search package --remote=conancenter`
`Version conflict`	Different packages need different versions	Use version overrides
`CMake not found`	CMake not installed	Install CMake or add to tool_requires
`Compiler not detected`	No C++ compiler installed	Install GCC/Clang/Visual Studio
`SSL verification failed`	Certificate issues	Update CA certificates
`Authentication failed`	Wrong credentials	Use tokens, not passwords
`No space left on device`	Disk full	Clean cache or move to larger disk
`Profile not found`	Missing profile	Create profile or use default
`Include file not found`	Header paths incorrect	Use Conan-generated CMake files

Key Points: Troubleshooting

Start with basics - Version, profile, and connectivity checks
Use verbose output - --verbose, --debug, --trace flags
Clear cache when stuck - conan cache clean "*"
Check dependencies first - Many issues are dependency conflicts
Verify build tools - CMake, compilers must be installed
Profile management - Most configuration issues are profile-related
Remote authentication - Use tokens, check connectivity
Clean slate approach - When stuck, clear everything and start fresh

VAD

ASR

TTS

llama-swap

llama.cpp

EDK2-UEFI

U-Boot

Yocto

QEMU

QNX

AUTOSAR Adaptive

MISRA C++

ASIL

ASPICE

Conan

Artifactory

Jenkins

Troubleshooting Guide