# CMake Error: toolchain file not found or invalid: /path/to/toolchain.cmake

- **ID:** `cmake/toolchain-file-not-found`
- **Domain:** cmake
- **Category:** config_error
- **Verification:** ai_generated
- **Fix Rate:** 92%

## Root Cause

The path specified via -DCMAKE_TOOLCHAIN_FILE does not exist, is not a file, or contains syntax errors.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| CMake 3.10 | active | — | — |
| CMake 3.18 | active | — | — |
| CMake 3.26 | active | — | — |

## Workarounds

1. **Use absolute path: cmake -DCMAKE_TOOLCHAIN_FILE=/full/path/to/toolchain.cmake /path/to/source** (95% success)
   ```
   Use absolute path: cmake -DCMAKE_TOOLCHAIN_FILE=/full/path/to/toolchain.cmake /path/to/source
   ```
2. **Check file existence: ls -la /path/to/toolchain.cmake and verify it has no syntax errors by running cmake -P /path/to/toolchain.cmake.** (90% success)
   ```
   Check file existence: ls -la /path/to/toolchain.cmake and verify it has no syntax errors by running cmake -P /path/to/toolchain.cmake.
   ```
3. **Set the toolchain file in a cache variable before project(): set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/toolchain.cmake" CACHE PATH "")** (85% success)
   ```
   Set the toolchain file in a cache variable before project(): set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/toolchain.cmake" CACHE PATH "")
   ```

## Dead Ends

- **** — CMake resolves relative paths from the build directory, not the source directory; leads to 'not found'. (70% fail)
- **** — Toolchain file must be set before the first project() command; otherwise CMake ignores it. (85% fail)