tools-only Troubleshooting Guide - DevOps Automation Pack
Quick solutions to common problems
Last Updated: October 10, 2025
Quick Diagnosis
Start here to identify your issue:
| Symptom | Likely Cause | Jump To |
|---|---|---|
| Commands not found | Installation issue | #1 |
| Commands error immediately | Permission or Git config | #2 |
| Smart commit shows no changes | Git staging issue | #7 |
| PR creation fails | No remote or branch issue | #8 |
| Docker commands fail | Docker not running | #11 |
| K8s commands fail | kubectl not configured | #13 |
| Terraform commands fail | Terraform not installed | #15 |
| Slow performance | Large repository or network | #18 |
Installation Issues
1. Commands Not Found After Installation
Symptoms:
/commit-smart
# Error: Unknown command '/commit-smart'
Cause: Plugin pack not installed correctly or Claude Code needs restart.
Solution:
Step 1: Verify installation
claude plugin list
You should see devops-automation-pack in the list.
Step 2: If not listed, reinstall
claude plugin install ~/Downloads/DevOps_Automation_Pack
Step 3: Restart Claude Code completely
# Close Claude Code window
# Reopen Claude Code
# Try command again
Still not working?
# Check installation directory
ls ~/.claude/plugins/
# Should see: devops-automation-pack/
If directory missing, reinstall from download location.
2. Command Fails: "Permission Denied"
Symptoms:
/github-actions-create
# Error: Permission denied: cannot write to .github/workflows/
Cause: No write permission in current directory.
Solution:
Check directory permissions:
ls -la .github/workflows/
Fix permissions:
# If directory doesn't exist, create it
mkdir -p .github/workflows
# If permission denied
sudo chown -R $USER:$USER .github/
For scripts:
# Make scripts executable
chmod +x scripts/*.sh
3. Plugin Installation Fails: "Already Exists"
Symptoms:
claude plugin install DevOps_Automation_Pack
# Error: Plugin 'devops-automation-pack' already installed
Cause: Old version still installed.
Solution:
Uninstall old version first:
claude plugin uninstall devops-automation-pack
Then install new version:
claude plugin install ~/Downloads/DevOps_Automation_Pack
Verify version:
claude plugin list | grep devops
# Should show: devops-automation-pack (v1.0.0)
Git Workflow Issues
4. Git Not Configured
Symptoms:
/commit-smart
# Error: Please tell me who you are
# Error: Run 'git config --global user.email'
Cause: Git user identity not configured.
Solution:
Set your identity globally:
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
Verify configuration:
git config --list | grep user
# Should show:
# user.name=Your Name
# [email protected]
Set per-project (optional):
cd your-project
git config user.name "Your Name"
git config user.email "[email protected]"
5. Not in a Git Repository
Symptoms:
/branch-create
# Error: fatal: not a git repository
Cause: Current directory is not a Git repository.
Solution:
Initialize Git repository:
git init
Or navigate to existing repository:
cd /path/to/your/project
Verify you're in a Git repo:
git status
# Should NOT say "not a git repository"
6. Branch Already Exists
Symptoms:
/branch-create
# Prompt: feature/user-auth
# Error: fatal: A branch named 'feature/user-auth' already exists
Cause: Branch name already in use.
Solution:
Option 1: Use different branch name
/branch-create
# Try: feature/user-auth-v2
Option 2: Delete old branch (if safe)
# View all branches
git branch -a
# Delete local branch (if not needed)
git branch -d feature/user-auth
# Force delete if has unmerged changes
git branch -D feature/user-auth
Option 3: Switch to existing branch
git checkout feature/user-auth
7. /commit-smart Says "No Changes to Commit"
Symptoms:
/commit-smart
# Error: No changes to commit
Cause: No files staged for commit.
Solution:
Stage your changes first:
# Stage all changes
git add .
# Or stage specific files
git add src/file.js
# Verify files are staged
git status
Then try commit again:
/commit-smart
Alternative: Stage changes automatically
Most commands auto-stage. If not working:
# Commit with auto-stage
git add . && /commit-smart
8. /pr-create Fails: "No Remote Configured"
Symptoms:
/pr-create
# Error: No remote repository configured
Cause: Local repository not connected to GitHub/GitLab.
Solution:
Add remote repository:
# GitHub
git remote add origin https://github.com/username/repo.git
# GitLab
git remote add origin https://gitlab.com/username/repo.git
Verify remote:
git remote -v
# Should show:
# origin https://github.com/username/repo.git (fetch)
# origin https://github.com/username/repo.git (push)
Push branch to remote:
git push -u origin your-branch-name
Then create PR:
/pr-create
9. Push Fails: "Authentication Failed"
Symptoms:
git push
# Error: Authentication failed
Cause: No GitHub/GitLab credentials configured.
Solution:
For HTTPS (use personal access token):
# GitHub: Create token at https://github.com/settings/tokens
# Use token as password when prompted
# Or configure credential helper
git config --global credential.helper cache
For SSH (recommended):
# Generate SSH key
ssh-keygen -t ed25519 -C "[email protected]"
# Add key to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
# Copy public key
cat ~/.ssh/id_ed25519.pub
# Add to GitHub: Settings → SSH Keys → New SSH key
Switch remote to SSH:
git remote set-url origin [email protected]:username/repo.git
CI/CD Issues
10. GitHub Actions Workflow Syntax Error
Symptoms:
/github-actions-create
# Workflow created, but GitHub shows syntax error
Cause: YAML indentation or structure issue.
Solution:
Validate YAML syntax:
# Install yamllint
pip install yamllint
# Check workflow file
yamllint .github/workflows/ci.yml
Common YAML mistakes:
# WRONG: Mixed tabs and spaces
jobs:
build:
runs-on: ubuntu-latest
# CORRECT: Use spaces only
jobs:
build:
runs-on: ubuntu-latest
Fix with GitHub's validator:
- Go to repository → Actions
- Click "New workflow"
- Paste your YAML
- GitHub will show syntax errors
Docker Issues
11. Docker Commands Fail: "Docker Daemon"
Symptoms:
/docker-optimize
# Error: Cannot connect to Docker daemon
Cause: Docker not running.
Solution:
Start Docker:
On Mac:
open -a Docker
# Wait for Docker icon in menu bar to show "running"
On Linux:
sudo systemctl start docker
sudo systemctl enable docker # Start on boot
On Windows:
# Start Docker Desktop from Start Menu
Verify Docker is running:
docker ps
# Should NOT say "Cannot connect to Docker daemon"
12. Dockerfile Build Fails: "No Such File"
Symptoms:
docker build -t myapp .
# Error: COPY failed: no such file or directory
Cause: Dockerfile references files not in build context.
Solution:
Check build context:
# List files Docker can see
docker build --no-cache -t test . 2>&1 | grep "COPY"
Common mistakes:
# WRONG: File outside context
COPY ../config.json /app/
# CORRECT: File in context
COPY config.json /app/
Fix: Copy files into context first
# Copy file into project directory
cp ../config.json ./config.json
# Then build
docker build -t myapp .
Kubernetes Issues
13. Kubernetes Commands Fail: "Connection Refused"
Symptoms:
/k8s-troubleshoot pod-name
# Error: Unable to connect to server: connection refused
Cause: kubectl not configured to connect to cluster.
Solution:
Verify kubectl configured:
kubectl cluster-info
# Should show cluster endpoint
If not configured, set up kubeconfig:
For GKE:
gcloud container clusters get-credentials CLUSTER_NAME --region REGION
For EKS:
aws eks update-kubeconfig --name CLUSTER_NAME --region REGION
For local (minikube):
minikube start
Verify connection:
kubectl get nodes
# Should list cluster nodes
14. Pod Troubleshooting Shows "Not Found"
Symptoms:
/k8s-troubleshoot my-pod
# Error: Pod 'my-pod' not found
Cause: Pod name incorrect or pod in different namespace.
Solution:
List all pods:
kubectl get pods --all-namespaces
Get exact pod name:
kubectl get pods | grep my-app
# Copy full pod name (includes random suffix)
# Example: my-app-7f9d6c-xk2m9
Specify namespace if needed:
kubectl get pods -n production
/k8s-troubleshoot my-pod -n production
Terraform Issues
15. Terraform Commands Fail: "Command Not Found"
Symptoms:
/terraform-module-create
# Error: terraform: command not found
Cause: Terraform not installed.
Solution:
Install Terraform:
On Mac:
brew install terraform
On Linux:
wget https://releases.hashicorp.com/terraform/1.6.0/terraform_1.6.0_linux_amd64.zip
unzip terraform_1.6.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/
On Windows:
choco install terraform
Verify installation:
terraform --version
# Should show: Terraform v1.6.0 or higher
16. Terraform Plan Analysis Fails: "Invalid JSON"
Symptoms:
/terraform-plan-analyze plan.json
# Error: Invalid JSON format
Cause: Terraform plan not exported correctly.
Solution:
Export plan correctly:
# Step 1: Create plan
terraform plan -out=plan.out
# Step 2: Convert to JSON
terraform show -json plan.out > plan.json
# Step 3: Verify JSON valid
cat plan.json | jq empty
# Step 4: Analyze
/terraform-plan-analyze plan.json
If still fails:
# Check file size
ls -lh plan.json
# If too large (>10MB), filter:
terraform show -json plan.out | jq '.resource_changes' > plan.json
General Performance Issues
17. Commands Hang or Take Too Long
Symptoms:
/commit-smart
# (command runs for 60+ seconds)
Cause: Large repository or many files.
Solution:
For commit commands:
# Commit specific paths only
git add src/
/commit-smart
For analysis commands:
# Analyze specific directory
cd src/
/docker-optimize
Check repository size:
du -sh .git/
# If >1GB, repository is large
Optimize Git repository:
git gc --aggressive
git prune
18. Commands Are Slow or Timeout
Symptoms:
/github-actions-create
# Error: Operation timed out after 60s
Cause: Network issues or API rate limits.
Solution:
Check network connectivity:
ping github.com
# Should show responses
Check API rate limits:
GitHub:
curl https://api.github.com/rate_limit
# Shows remaining API calls
If rate limited, wait or authenticate:
# Set GitHub token
export GITHUB_TOKEN=your_token_here
Increase timeout (advanced):
# Set in plugin config
claude config set timeout 120
Agent Issues
19. AI Agent Not Activating
Symptoms:
# Ask about CI/CD
"How do I optimize my pipeline?"
# Generic response instead of CI/CD Expert Agent
Cause: Query not triggering agent activation.
Solution:
Be more specific in questions:
"How do I make my code better?" "How do I optimize my GitHub Actions pipeline?"
"I have Docker issues" "My Docker image is 2GB, how do I reduce it?"
Explicitly invoke agent (if available):
/ci-cd-expert "optimize my pipeline"
/docker-specialist "reduce image size"
20. Hooks Not Firing
Symptoms:
# Edit file
# No automatic formatting or validation
Cause: Hooks not configured or disabled.
Solution:
Verify hooks enabled:
claude plugin hooks list
# Should show devops-automation-pack hooks
Enable hooks if disabled:
claude plugin hooks enable devops-automation-pack
Check hook configuration:
cat ~/.claude/plugins/devops-automation-pack/hooks/hooks.json
Still Having Issues?
If your problem isn't listed here:
1. Check Logs
# View Claude Code logs
claude logs
# View last 50 lines
claude logs --tail 50
2. Verify Prerequisites
# Check Claude Code version
claude --version
# Should be 1.5.0 or higher
# Check plugin version
claude plugin list | grep devops
# Should show version 1.0.0
3. Get Help
Email Support:
- Address: mandy@intentsolutions.io
- Include:
- Exact error message (copy-paste)
- Command you ran
- Operating system
- Claude Code version
- Plugin version
Response time: Within 24 hours
Quick Fix Checklist
Before contacting support, try these:
- Restart Claude Code
- Verify plugin installed:
claude plugin list - Check you're in Git repository:
git status - Verify Git configured:
git config user.name - Check Docker running (if using Docker commands):
docker ps - Verify kubectl configured (if using K8s commands):
kubectl get nodes - Check Terraform installed (if using Terraform commands):
terraform --version - View logs:
claude logs --tail 50
Document Version: 1.0.0 Pack Version: 1.0.0 Last Updated: October 10, 2025