# Troubleshooting
Common issues and solutions.
## Installation Issues
### "command not found: cm"
**Cause**: Binary not in PATH.
**Solution**:
```bash
# Check if binary exists
ls -la target/release/cm
# Add to PATH
export PATH="$PATH:/path/to/checkmate/target/release"
# Or install globally
sudo cp target/release/cm /usr/local/bin/
```
### Build Fails
**Cause**: Missing Rust toolchain or dependencies.
**Solution**:
```bash
# Install Rust
# Update Rust
rustup update
# Clean and rebuild
cargo clean
cargo build --release
```
## Initialization Issues
### "No .checkmate/ found"
**Cause**: Project not initialized.
**Solution**:
```bash
cm init --url http://your-api-url
```
### "Already initialized"
**Cause**: `.checkmate/` already exists.
**Solution**:
```bash
# Remove and reinitialize
rm -rf .checkmate
cm init --url http://your-api-url
```
### "Base URL required in non-interactive mode"
**Cause**: Running `cm init` without TTY and without `--url`.
**Solution**:
```bash
cm init --url http://localhost:8080
```
## Test Discovery Issues
### "No test specs found"
**Cause**: No YAML files in `.checkmate/tests/`.
**Solution**:
```bash
# Check directory
ls .checkmate/tests/
# Create a test spec
cat > .checkmate/tests/health.yaml << 'EOF'
name: "Health Check"
tests:
api_health:
endpoint: /health
EOF
```
### Tests Not Running
**Cause**: File extension not `.yaml` or `.yml`.
**Solution**:
```bash
# Rename file
mv .checkmate/tests/test.txt .checkmate/tests/test.yaml
```
### Spec Not Found by Name
**Cause**: Name doesn't match file.
**Solution**:
```bash
# Use exact filename (without extension)
cm test run users # Looks for users.yaml or users.yml
# Or use full path
cm test run .checkmate/tests/users.yaml
```
## Connection Issues
### "Connection refused"
**Cause**: API not running or wrong URL.
**Solution**:
```bash
# Check config
cm config show
# Verify API is running
curl http://localhost:8080/health
# Override URL
CM_ENV__BASE_URL="http://correct-url:8080" cm test run
```
### Timeout Errors
**Cause**: Request taking too long.
**Solution**:
```bash
# Increase timeout
CM_ENV__TIMEOUT_MS=30000 cm test run
# Or in config.toml
[env]
timeout_ms = 30000
```
### SSL/TLS Errors
**Cause**: Certificate issues.
**Solution**:
```bash
# For self-signed certs in development
# (Note: Not recommended for production)
```
## Configuration Issues
### Config Not Applied
**Cause**: Wrong priority or syntax error.
**Solution**:
```bash
# Check current config
cm config show
# Check sources
cm config sources
# Verify TOML syntax
cat .checkmate/config.toml
```
### Environment Variables Not Working
**Cause**: Wrong variable name format.
**Solution**:
```bash
# Use double underscore for nesting
CM_ENV__BASE_URL="http://example.com" # Correct
CM_ENV_BASE_URL="http://example.com" # Wrong
# Verify it's set
echo $CM_ENV__BASE_URL
```
## Assertion Issues
### Query Returns Null
**Cause**: Path doesn't exist in response.
**Solution**:
```bash
# Test query manually
cm clove eval '$[field]' '{"other": "value"}'
# Use existence check
- query: "$[field]?"
expect: true
```
### Type Mismatch
**Cause**: Expecting wrong type.
**Solution**:
```yaml
# Check actual type
- query: "$[count]"
expect_type: number # Not string
# Numbers must not be quoted
- query: "$[count]"
expect: 42 # Not "42"
```
### Previous Response Not Available
**Cause**: Only one request in test.
**Solution**:
```yaml
# Need multiple requests for @prev
tests:
multi_request:
requests: [request1, request2]
assertions:
- query: "$[value]"
expect_gt: "$[@prev][value]"
```
## History Issues
### "No test runs recorded"
**Cause**: No tests have been run yet.
**Solution**:
```bash
cm test run
cm history
```
### History Not Saving
**Cause**: `.checkmate/runs/` not writable.
**Solution**:
```bash
# Check permissions
ls -la .checkmate/runs/
# Fix permissions
chmod 755 .checkmate/runs/
```
### Git Context Missing
**Cause**: Not in a git repository.
**Solution**:
```bash
# Initialize git
git init
# Or history will show without git context
```
## Hook Issues
### Hook Not Running
**Cause**: Not executable or wrong location.
**Solution**:
```bash
# Check file exists
ls -la .checkmate/hooks/
# Make executable
chmod +x .checkmate/hooks/on_fail
# Check shebang
head -1 .checkmate/hooks/on_fail
# Should be: #!/bin/bash
```
### Hook Errors
**Cause**: Script error.
**Solution**:
```bash
# Test manually
CM_RUN_ID="test" CM_FAILED=1 CM_TOTAL=5 ./.checkmate/hooks/on_fail
# Check script syntax
bash -n .checkmate/hooks/on_fail
```
### Environment Variables Not Set
**Cause**: Using unavailable variable in hook.
**Solution**:
```bash
# Check what's available (see HOOKS.md)
# pre_run only has CM_SPEC
# post_run/on_pass/on_fail have all variables
```
## Performance Issues
### Slow Tests
**Cause**: Network latency or slow API.
**Solution**:
```bash
# Increase timeout
CM_ENV__TIMEOUT_MS=30000 cm test run
# Run specific tests
cm test run health --test api_responds
```
### Memory Issues
**Cause**: Large responses or many tests.
**Solution**:
```bash
# Run specs individually
cm test run users
cm test run orders
```
## Getting Help
### Documentation
```bash
cm docs # Overview
cm doc <topic> # Specific topic
cm onboard # Quick reference
```
### Debug Output
```bash
cm test run -v # Verbose
```
### Report Issues
Include:
1. Command run
2. Error message
3. `cm --version`
4. `cm config show`
5. Relevant spec file
---
## See Also
- [FAQ](FAQ.md) - Common questions
- [CLI Reference](CLI_REFERENCE.md) - All commands