Troubleshooting Guide

December 26, 2025 · View on GitHub

Common issues and solutions for LDF users.

Installation Issues
Command Not Found Errors
Linting Errors
Project Initialization Problems
MCP Server Issues
Coverage Problems
Platform-Specific Issues
FAQ

Installation Issues

Python version too old

Error:

ERROR: ldf requires Python 3.10 or later

Solution:

macOS:

# Install Python 3.12
brew install python@3.12
# Or download from python.org

Windows:

Download Python 3.12 from https://www.python.org/downloads/
⚠️ Check "Add python.exe to PATH" during installation

Linux (Ubuntu/Debian):

sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11

Linux (Fedora/RHEL):

sudo dnf install python3.11

pip install fails with "No matching distribution"

Error:

ERROR: Could not find a version that satisfies the requirement ldf

Causes:

Python version too old (< 3.10)
pip not updated
Network/proxy issues

Solutions:

Check Python version:

python3 --version  # Must be 3.10+

Update pip:

python3 -m pip install --upgrade pip

Try with --user:

pip3 install --user ldf

Behind proxy:

pip3 install ldf --proxy http://proxy.company.com:8080

Permission denied errors

Error:

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied

Solution: Install with --user flag

pip3 install --user ldf

Why: Installs to your user directory, no sudo needed.

Then add to PATH if needed:

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

# Windows
# Add %APPDATA%\Python\Python312\Scripts to PATH

Command Not Found Errors

"ldf: command not found" (macOS/Linux)

Cause: ~/.local/bin not in PATH.

Solution:

Add to PATH:

export PATH="$HOME/.local/bin:$PATH"

Make permanent:

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify:

which ldf
# Should show: /Users/yourname/.local/bin/ldf

"'ldf' is not recognized" (Windows)

Cause: Python Scripts folder not in PATH.

Solution:

Find Python Scripts folder:

pip show ldf

Look for "Location:" line, e.g.:

Location: C:\Users\YourName\AppData\Local\Programs\Python\Python312\Lib\site-packages

The Scripts folder is:

C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts

Add to PATH:

Press Windows key + R
Type sysdm.cpl and press Enter
Click Advanced tab
Click Environment Variables
Edit Path under User variables
Click New and add Scripts path
Click OK on all windows

Restart terminal and verify:

ldf --version

"pip3: command not found"

Cause: pip not installed or not in PATH.

Solution:

macOS/Linux:

# Download get-pip.py
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

# Install pip
python3 get-pip.py --user

# Verify
pip3 --version

Windows: Reinstall Python with "Install pip" option checked.

Linting Errors

"Guardrail matrix incomplete"

Error:

ERROR: Guardrail matrix incomplete - missing guardrails: 6, 7

Cause: Not all 8 core guardrails (+ preset guardrails) listed in matrix.

Solution:

Ensure table has all guardrails:

Core 8:

Testing Coverage
Security Basics
Error Handling
Logging & Observability
API Design
Data Validation
Database Migrations
Documentation

Plus preset guardrails if using:

SaaS: +5 guardrails
Fintech: +7 guardrails
Healthcare: +6 guardrails
API-only: +4 guardrails

Example:

| Guardrail | Requirements | Design | Tasks/Tests | Owner | Status |
|-----------|--------------|--------|-------------|-------|--------|
| 1. Testing Coverage | [US-1] | TBD | TBD | Dev | TODO |
| 2. Security Basics | [US-2] | TBD | TBD | Dev | TODO |
| 3. Error Handling | [US-1] | TBD | TBD | Dev | TODO |
| 4. Logging & Observability | [US-1] | TBD | TBD | Dev | TODO |
| 5. API Design | [US-1] | TBD | TBD | Dev | TODO |
| 6. Data Validation | [US-1] | TBD | TBD | Dev | TODO |
| 7. Database Migrations | [US-3] | TBD | TBD | DB | TODO |
| 8. Documentation | [US-1] | TBD | TBD | TechWriter | TODO |

"Guardrail marked N/A without reason"

Error:

ERROR: Guardrail 6 marked N/A but no reason provided

Cause: Marked N/A in table but didn't explain why.

Solution:

Bad:

| 6. Data Validation | N/A | N/A | N/A | - | N/A |

Good:

| 6. Data Validation | N/A - No user input parameters | N/A | N/A | - | N/A |

"Template markers found"

Error:

ERROR: Template markers [TBD] or [TODO] found in spec

Cause: Left placeholder text in requirements/design/tasks files.

Solution:

Replace all placeholders:

[TBD] → Specific content or "N/A - reason"
[TODO] → Actual content
[FILL THIS IN] → Real values

Find all placeholders:

grep -r "\[TBD\]" .ldf/specs/
grep -r "\[TODO\]" .ldf/specs/

"No user stories found"

Error:

ERROR: No user stories found in requirements.md

Cause: Missing user stories or incorrect formatting.

Solution:

Ensure you have at least one user story with this format:

### US-1: Story Title

**As a** [role]
**I want to** [capability]
**So that** [benefit]

**Acceptance Criteria:**
- [ ] AC-1.1: Specific criterion
- [ ] AC-1.2: Another criterion

Required elements:

### US-X: heading
**As a**, **I want to**, **So that** lines
**Acceptance Criteria:** section
At least one - [ ] AC-X.Y: item

"Acceptance criteria not testable"

Warning:

WARNING: AC-1.2 may not be testable - too vague

Cause: Acceptance criteria like "works correctly" or "is fast".

Solution:

Vague (bad):

AC-1.1: Login works correctly
AC-1.2: System is fast

Specific (good):

AC-1.1: Login returns 200 OK with JWT token on valid credentials
AC-1.2: Login endpoint responds in < 500ms at p95

Project Initialization Problems

"Not in an LDF project"

Error:

ERROR: Not in an LDF project. Run 'ldf init' first.

Cause: Trying to run LDF commands outside an initialized directory.

Solution:

Check for .ldf directory:

ls -la .ldf  # Should exist

If missing, initialize:

ldf init

Or navigate to correct directory:

cd /path/to/my-ldf-project

".ldf directory already exists"

Error:

ERROR: .ldf directory already exists. Use --force to overwrite.

Cause: Trying to reinitialize an LDF project.

Solutions:

Repair existing setup:

ldf init --repair

Start fresh (destructive):

rm -rf .ldf AGENT.md .agent
ldf init

Upgrade framework files only:

ldf update

"Invalid preset name"

Error:

ERROR: Unknown preset 'webapp'. Valid presets: saas, fintech, healthcare, api-only, custom

Cause: Typo in preset name.

Solution:

Use valid preset:

ldf init --preset saas       # ✓ Correct
ldf init --preset webapp     # ✗ Invalid

List available presets:

ldf list-presets

MCP Server Issues

"MCP servers not installed"

Error:

WARNING: MCP servers requested but 'mcp' package not installed

Solution:

pip install llm-ldf[mcp]

Verify:

ldf mcp-health

"MCP server unhealthy"

Error:

ERROR: spec_inspector MCP server not responding

Causes & Solutions:

MCP package not installed:

pip install llm-ldf[mcp]

Python version too old:

python3 --version  # Must be 3.10+

Corrupted installation:

pip uninstall ldf
pip install llm-ldf[mcp]

Check server status:

ldf mcp-health --server spec_inspector

"MCP config not found"

Error:

ERROR: .agent/mcp.json not found

Solution:

mkdir -p .agent
ldf mcp-config > .agent/mcp.json

Coverage Problems

"Coverage data not found"

Error:

ERROR: No coverage data found. Run tests with coverage first.

Cause: Haven't run tests with coverage tracking.

Solution:

Python (pytest):

pytest --cov=your_package --cov-report=json

Then:

ldf coverage

"Coverage below threshold"

Error:

ERROR: Coverage 75% is below required 80%

Cause: Test coverage doesn't meet target.

Solutions:

Write more tests
Lower threshold (not recommended):

ldf coverage --fail-under 70

Check which files need coverage:

ldf coverage --verbose

Platform-Specific Issues

macOS: VS Code "command not found" in terminal

Cause: VS Code shell integration not installed or PATH not loaded.

Solution:

Install shell integration:
- Open VS Code
- Press Cmd + Shift + P
- Type: shell command
- Select: "Shell Command: Install 'code' command in PATH"
Restart VS Code completely (Cmd+Q, then reopen)
Check shell:

echo $SHELL

If /bin/bash, edit ~/.bash_profile If /bin/zsh, edit ~/.zshrc

Windows: PowerShell execution policy blocks scripts

Error:

ldf : File cannot be loaded because running scripts is disabled on this system

Solution:

Run PowerShell as Administrator:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Explanation: Allows local scripts, still protects against remote scripts.

Linux: "externally-managed-environment" error

Error:

error: externally-managed-environment

Cause: Debian/Ubuntu blocks system-wide pip installs.

Solution 1 - Use --user (recommended):

pip3 install --user ldf

Solution 2 - Use virtual environment:

python3 -m venv ~/.venv/ldf
source ~/.venv/ldf/bin/activate
pip install llm-ldf

Linux: SELinux blocks operations (Fedora/RHEL)

Error:

Permission denied (SELinux)

Solution:

Temporary (for testing):

sudo setenforce 0

Permanent (less secure):

sudo setsebool -P allow_execmem 1

Best (create policy):

# Run command that fails, then:
sudo audit2allow -a -M ldf
sudo semodule -i ldf.pp

FAQ

Q: Do I need to use all three phases for every feature?

A: No. Use LDF for significant features only.

Use LDF for:

✅ New features
✅ Security-sensitive changes
✅ Public APIs
✅ Database schema changes
✅ >200 lines of code

Skip LDF for:

❌ Bug fixes (link to issue)
❌ Documentation updates
❌ Config changes
❌ Small refactorings

Q: What if I don't know the answer to a question-pack question?

A: Mark it as "TBD - needs research" in the answerpack YAML file, and add to "Outstanding Questions" section in requirements.md.

Don't proceed to design phase until all critical questions are answered.

Why: These questions surface critical decisions early when they're cheap to make.

Q: Can I change requirements after approval?

A: Yes, but update the spec file and re-lint.

Best practice:

Update requirements.md
Run ldf lint <spec>
If design/tasks exist, update those too
Commit changes to version control

The spec should always match what you're building.

Q: Do I really need the guardrail coverage matrix?

A: Yes - it's the most important part of requirements.md.

Why:

Forces thinking about quality constraints upfront
Prevents bugs by ensuring nothing is forgotten
Makes review easier (reviewers can scan matrix)
Tracks who owns each quality concern

Many production bugs are prevented by properly filling this out.

Q: How detailed should requirements.md be?

A: Enough to answer "what" but not "how".

Include:

User stories (As a... I want... So that...)
Acceptance criteria (testable, measurable)
Question-pack answer summaries
Complete guardrail coverage matrix

Don't include:

Implementation details (save for design.md)
Specific code (save for tasks.md)
Technology choices (save for design.md)

Example:

Good: "AC-1.1: Login returns 401 for invalid credentials"

Too vague: "AC-1.1: Login works correctly"

Too detailed: "AC-1.1: FastAPI route /login with bcrypt cost 12 returns HTTPException(401)"

Q: What's the difference between `ldf init` and `ldf create-spec`?

ldf init - Run once per project to set up LDF
ldf create-spec - Run once per feature to create a spec

Example workflow:

# Once: Set up project
ldf init

# Many times: Create specs for features
ldf create-spec user-auth
ldf create-spec payment-processing
ldf create-spec admin-dashboard