Skip to main content

Troubleshooting Guide

Quick Diagnostics​

specifyx check              # Verify installation and requirements
specifyx config validate    # Check configuration
specifyx --version          # Show version info
specifyx run --list         # Check project structure

Installation Issues​

Command Not Found​

# Check installation
uv tool list | grep specifyx
pipx list | grep specifyx

# Reinstall
uv tool install specifyx    # Recommended
pipx install specifyx       # Alternative
uvx specifyx                # Run without install

Python Version Issues​

SpecifyX requires Python 3.11+. Check with python --version and install newer version if needed:

uv python install 3.11     # Using uv
pyenv install 3.11.5       # Using pyenv

Permission Issues​

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

# Use user install
pip install --user specifyx

Configuration Issues​

Invalid Configuration​

Error: Invalid branch pattern or Configuration validation failed

Fix: Check .specify/config.toml syntax:

[project]
name = "my-project"

[branching] 
patterns = ["feature/{feature-name}", "main"]
validation_rules = ["lowercase_only"]

Template Errors​

Error: Template not found or Jinja2 syntax error

Fix:

  1. Check template exists in .specify/templates/
  2. Validate Jinja2 syntax
  3. Reset templates: rm -rf .specify/templates && specifyx init --here

Project Issues​

Git Repository Required​

Error: Not a git repository

Fix: Initialize git repo: git init && git add . && git commit -m "Initial commit"

Branch Creation Failures​

Error: Branch already exists or Invalid branch name

Fix:

  1. Use unique branch names
  2. Check branch naming patterns in config
  3. Delete existing branch: git branch -D branch-name

Command Execution​

Script Not Found​

Error: Script 'xyz' not found

Fix:

  1. List available scripts: specifyx run --list
  2. Check .specify/scripts/ directory
  3. Regenerate scripts: specifyx init --here

Execution Failures​

Error: Scripts fail to run

Fix:

  1. Check Python dependencies: pip install -r requirements.txt
  2. Verify script permissions: chmod +x .specify/scripts/*
  3. Check script syntax manually

AI Assistant Issues​

Claude Code Integration​

Error: Commands not working in Claude Code

Fix:

  1. Ensure project has been initialized: specifyx init
  2. Check .claude/commands/ directory exists
  3. Regenerate commands: specifyx refresh-templates
  4. Verify CLAUDE.md includes project context

Agent Template Errors​

Error: AI assistant prompts not generating correctly

Fix:

  1. Check assistant configuration: specifyx config show
  2. Validate assistant is supported: specifyx add-ai --list
  3. Regenerate templates: specifyx refresh-templates --ai your-assistant

Documentation Issues​

Auto-generated Docs Out of Sync​

Error: API reference doesn't match code

Fix:

cd docs
pnpm generate          # One-time generation
pnpm generate:watch    # Continuous updates during development
pnpm dev              # Development server with auto-sync

Build Failures​

Error: Documentation build fails

Fix:

  1. Check Node.js version: node --version (requires 18+)
  2. Install dependencies: cd docs && pnpm install
  3. Clear cache: rm -rf docs/.docusaurus docs/build
  4. Rebuild: pnpm build

Performance Issues​

Slow Operations​

  • Template rendering: Reduce template complexity
  • Large projects: Use .specifyignore to exclude files
  • Network issues: Check internet connection for updates

Platform-Specific​

Windows​

  • Use WSL2 for best compatibility
  • Install Python via Microsoft Store or python.org
  • Check PATH includes Python and Scripts directories

macOS​

  • Install via Homebrew: brew install python@3.11
  • May need to install Xcode Command Line Tools

Linux​

  • Install Python dev packages: apt install python3.11-dev
  • Check $HOME/.local/bin is in PATH

Getting Help​

Collect Diagnostics​

specifyx check --verbose     # Detailed system info
specifyx --version          # Version info
python --version            # Python version
uv --version               # UV version (if used)

Log Files​

Check ~/.cache/specifyx/logs/ for detailed error logs.

Support​