Troubleshooting - Spec Kit

This guide covers common issues you might encounter when using Spec Kit and their solutions.

Installation Issues

Specify CLI Not Found

Error: command not found: specify

Symptoms: After installing with uv tool install, specify command not found.Solutions:

Check if installed:
```
uv tool list
```
Verify PATH includes uv tools:
```
echo $PATH | grep -o "[^:]*uv[^:]*"
```

Add to PATH (if missing):

# For bash/zsh
export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Reinstall with force:

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

UV Not Installed

Error: command not found: uv

Solution: Install uv package manager:

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: Using pip
pip install uv

Then retry installing Specify CLI.

Python Version Issues

Error: Python 3.11+ required

Symptoms: Error during installation about Python version.Solution: Install Python 3.11 or higher:

# Check current version
python --version

# Linux (apt)
sudo apt update
sudo apt install python3.11

# macOS (Homebrew)
brew install [email protected]

# Or use uv's Python management
uv python install 3.11

Git Authentication Issues

Git Credential Manager (Linux)

Error: Git authentication failing on Linux

Symptoms: Can’t push to GitHub, authentication errors.Solution: Install Git Credential Manager:

#!/usr/bin/env bash
set -e

echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb

echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb

echo "Configuring Git to use GCM..."
git config --global credential.helper manager

echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

echo "✓ Git Credential Manager installed"

Then retry git operations.

SSH Key Issues

Error: Permission denied (publickey)

Symptoms: Can’t clone/push using SSH.Solution: Set up SSH keys:

# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"

# Start SSH agent
eval "$(ssh-agent -s)"

# Add key to agent
ssh-add ~/.ssh/id_ed25519

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Add to GitHub: Settings → SSH and GPG keys → New SSH key

Verify connection:

ssh -T [email protected]

Branch and Feature Issues

Not on Feature Branch

Error: Not on a feature branch (###-name format)

Symptoms: Commands fail because you’re on main or other branch.Solution:

Create new feature:

# In your AI agent
/speckit.specify Build user authentication system

Or switch to existing feature:
```
git checkout 001-user-auth
```
For non-Git repos, set environment variable:
```
export SPECIFY_FEATURE="001-user-auth"
```

Feature Directory Not Found

Error: Feature directory not found: specs/001-feature

Symptoms: Scripts can’t find feature directory.Solution:

Verify branch matches directory:

# Check current branch
git branch

# List feature directories
ls specs/

Create missing directory:
```
mkdir -p specs/001-feature
```

Or create new feature properly:

# In AI agent
/speckit.specify Feature description

Branch Name Too Long

Warning: Branch name exceeded GitHub's 244-byte limit

Symptoms: Branch name automatically truncated.Solution: This is normal - the script automatically handles it. The warning is informational.To avoid truncation, use shorter feature descriptions or custom short names:

# Use --short-name option
./.specify/scripts/bash/create-new-feature.sh \
  "Very long feature description here" \
  --short-name "short-name"

Missing Prerequisites

Plan.md Not Found

Error: plan.md not found

Symptoms: /speckit.tasks or /speckit.implement fails.Solution: Create implementation plan first:

# In AI agent
/speckit.plan Use Python with FastAPI, PostgreSQL database

Verify plan exists:

ls specs/001-feature/plan.md

Tasks.md Not Found

Error: tasks.md not found

Symptoms: /speckit.implement fails.Solution: Generate task breakdown first:

# In AI agent
/speckit.tasks

Verify tasks exist:

ls specs/001-feature/tasks.md

Spec.md Not Found

Error: spec.md not found

Symptoms: /speckit.plan can’t find specification.Solution: Create specification first:

# In AI agent
/speckit.specify Build a photo album application

Verify spec exists:

ls specs/001-feature/spec.md

Agent-Specific Issues

Commands Not Appearing

Slash commands not showing in AI agent

Symptoms: /speckit.* commands not available in agent.Solution:

Verify commands installed:

# For Claude
ls .claude/commands/speckit.*.md

# For opencode
ls .opencode/command/speckit.*.md

# For Gemini
ls .gemini/commands/speckit.*.toml

Restart AI agent: Close and reopen the agent

Reinstall Specify:

# In project directory
specify init . --force --ai claude

Check agent running in correct directory:

pwd  # Should be in project root with .specify/ folder

Agent Can’t Find Files

Agent says it can't find spec files

Symptoms: Agent reports file not found errors.Solution:

Verify files exist:
```
ls -la specs/001-feature/
```

Update agent context:

# Bash
./.specify/scripts/bash/update-agent-context.sh

# PowerShell
.specify\scripts\powershell\update-agent-context.ps1

Check agent working directory:
- Agent should be started from project root
- Not from .specify/ or specs/ subdirectory

TOML vs Markdown Format

Error: Invalid command format for agent

Symptoms: Commands work in some agents but not others.Solution: Different agents use different formats:

Markdown (.md): Claude, Cursor, opencode, Windsurf, Amp, SHAI, Amazon Q
TOML (.toml): Gemini, Qwen

Reinstall with correct agent:

specify init . --force --ai gemini  # For TOML
specify init . --force --ai claude  # For Markdown

Extension Issues

Extension Not Found in Catalog

Error: Extension 'jira' not found in catalog

Symptoms: Can’t install extension by name.Solution:

Check catalog URL:
```
echo $SPECKIT_CATALOG_URL
```

Use community catalog or install from URL:

# Install from URL directly
specify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip

Populate your catalog: Copy extension entry from catalog.community.json to your organization’s catalog.json

Extension Configuration Missing

Error: Extension configuration not found

Symptoms: Extension commands fail due to missing config.Solution:

Create config from template:

cp .specify/extensions/jira/jira-config.template.yml \
   .specify/extensions/jira/jira-config.yml

Edit configuration:

vim .specify/extensions/jira/jira-config.yml

Or use environment variables:

export SPECKIT_JIRA_PROJECT_KEY="MYPROJECT"

Extension Version Incompatible

Error: Extension requires spec-kit >=0.2.0

Symptoms: Can’t install extension due to version mismatch.Solution:

Upgrade Spec Kit:
```
uv tool upgrade specify-cli
```

Or install older extension version:

specify extension add --from https://github.com/org/ext/archive/v1.0.0.zip

Script Issues

Script Not Executable

Error: Permission denied (Bash)

Symptoms: Can’t run bash scripts.Solution:

# Make scripts executable
chmod +x .specify/scripts/bash/*.sh

# Or run with bash
bash .specify/scripts/bash/create-new-feature.sh

Execution Policy (PowerShell)

Error: Running scripts is disabled (PowerShell)

Symptoms: Can’t run PowerShell scripts.Solution:

# Check current policy
Get-ExecutionPolicy

# Allow local scripts (recommended)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or bypass for single script
powershell -ExecutionPolicy Bypass -File .specify\scripts\powershell\create-new-feature.ps1

Script Output Encoding Issues

Error: Strange characters in output

Symptoms: Unicode characters appear as boxes or question marks.Solution:

# Bash: Ensure UTF-8 locale
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# PowerShell: Set output encoding
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Template Issues

Template Not Found

Error: Template not found at .specify/templates/

Symptoms: Commands can’t find template files.Solution:

Verify template directory exists:
```
ls .specify/templates/
```
Reinstall templates:
```
specify init . --force --ai claude
```
Or copy templates manually from Spec Kit repository

Template Variables Not Replaced

Placeholder text like [FEATURE NAME] remains in files

Symptoms: Template variables not substituted.Solution: This is expected - the AI agent is responsible for filling in placeholders.

Review generated file: Check if AI agent filled in values
Manually replace remaining placeholders

Or regenerate with more specific instructions:

# Be more explicit in commands
/speckit.specify Build a user authentication system with email/password login

Performance Issues

Slow Command Execution

Commands taking too long to complete

Possible causes and solutions:

Large codebase: AI agent scanning many files
- Add .gitignore entries for node_modules, build dirs
- Use .aiderignore or agent-specific ignore files
Network issues: Fetching git refs or catalogs
- Check internet connection
- Use local catalog for extensions
Too many extensions: Loading many extensions
- Disable unused extensions: specify extension disable <name>
- Only install what you need

Agent Out of Memory

AI agent crashes or runs out of memory

Solutions:

Split large features into smaller ones
Reduce context by focusing on specific files
Close and restart agent between major operations
Increase system memory if possible

Non-Git Workflows

SPECIFY_FEATURE Not Persisting

Error: Feature not detected after closing terminal

Symptoms: Must set SPECIFY_FEATURE every time.Solution:

Add to shell profile:

# In ~/.bashrc or ~/.zshrc
export SPECIFY_FEATURE="001-current-feature"

Or use direnv for automatic switching:

# Install direnv
# Create .envrc in project
echo 'export SPECIFY_FEATURE="001-feature"' > .envrc
direnv allow

Or always specify in commands:

SPECIFY_FEATURE="001-feature" ./script.sh

No Git, Scripts Fail

Warning: Git repository not detected

Symptoms: Scripts warn about Git not being available.Solution: This is informational - scripts automatically fall back to non-Git mode.

Branch creation is skipped
Feature detection uses SPECIFY_FEATURE or directory scan
All other functionality works normally

To suppress warnings:

# Set this in your environment
export SPECIFY_NO_GIT_WARNING=1

Validation Errors

Checklist Items Not Passing

Quality checklist validation failing

Symptoms: /speckit.checklist shows unchecked items.Solution:

Review each failed item: Read why it’s failing
Update artifacts: Fix issues in spec.md, plan.md, etc.
Re-run validation: Have AI agent check again

Use /speckit.analyze for automated consistency checks across artifacts.

Constitution Violations

Plan violates constitution principles

Symptoms: Constitution check shows violations.Solution:

Justify violations in Complexity Tracking table:
- Why the violation is needed
- Why simpler alternatives were rejected
Or revise plan to comply with constitution

Update constitution if principle is outdated:

/speckit.constitution Update principles to allow [specific case]

Getting Help

If your issue isn’t covered here, please open a GitHub issue with:

Detailed description of the problem
Steps to reproduce
Error messages (full text)
Environment info (OS, Python version, agent used)

Debug Information Collection

# Collect debug info
echo "Spec Kit Version:"
specify --version

echo "\nPython Version:"
python --version

echo "\nGit Version:"
git --version

echo "\nCurrent Branch:"
git branch --show-current

echo "\nFeature Directory:"
ls -la specs/

echo "\nInstalled Extensions:"
specify extension list

echo "\nAgent Command Files:"
ls -la .claude/commands/ .opencode/command/ .gemini/commands/ 2>/dev/null || echo "No agent command directories found"

Useful Commands

# Check Spec Kit installation
specify check

# Verify feature structure
tree .specify/ -L 2

# Test script directly
bash -x .specify/scripts/bash/check-prerequisites.sh

# View agent context
cat .claude/CLAUDE.md  # or .opencode/README.md, etc.

Support Channels

GitHub Issues: github.com/github/spec-kit/issues
Documentation: github.github.io/spec-kit/
Discussions: github.com/github/spec-kit/discussions

Get Started

Core Concepts

CLI Reference

Slash Commands

AI Agents

Advanced

​Installation Issues

​Specify CLI Not Found

​UV Not Installed

​Python Version Issues

​Git Authentication Issues

​Git Credential Manager (Linux)

​SSH Key Issues

​Branch and Feature Issues

​Not on Feature Branch

​Feature Directory Not Found

​Branch Name Too Long

​Missing Prerequisites

​Plan.md Not Found

​Tasks.md Not Found

​Spec.md Not Found

​Agent-Specific Issues

​Commands Not Appearing

​Agent Can’t Find Files

​TOML vs Markdown Format

​Extension Issues

​Extension Not Found in Catalog

​Extension Configuration Missing

​Extension Version Incompatible

​Script Issues

​Script Not Executable

​Execution Policy (PowerShell)

​Script Output Encoding Issues

​Template Issues

​Template Not Found

​Template Variables Not Replaced

​Performance Issues

​Slow Command Execution

​Agent Out of Memory

​Non-Git Workflows

​SPECIFY_FEATURE Not Persisting

​No Git, Scripts Fail

​Validation Errors

​Checklist Items Not Passing

​Constitution Violations

​Getting Help

​Debug Information Collection

​Useful Commands

​Support Channels

​Related Resources

Build docs developers (and LLMs) love

Installation Issues

Specify CLI Not Found

UV Not Installed

Python Version Issues

Git Authentication Issues

Git Credential Manager (Linux)

SSH Key Issues

Branch and Feature Issues

Not on Feature Branch

Feature Directory Not Found

Branch Name Too Long

Missing Prerequisites

Plan.md Not Found

Tasks.md Not Found

Spec.md Not Found

Agent-Specific Issues

Commands Not Appearing

Agent Can’t Find Files

TOML vs Markdown Format

Extension Issues

Extension Not Found in Catalog

Extension Configuration Missing

Extension Version Incompatible

Script Issues

Script Not Executable

Execution Policy (PowerShell)

Script Output Encoding Issues

Template Issues

Template Not Found

Template Variables Not Replaced

Performance Issues

Slow Command Execution

Agent Out of Memory

Non-Git Workflows

SPECIFY_FEATURE Not Persisting

No Git, Scripts Fail

Validation Errors

Checklist Items Not Passing

Constitution Violations

Getting Help

Debug Information Collection

Useful Commands

Support Channels

Related Resources