Troubleshooting

Tofie Troubleshooting Guide #

Common issues and their solutions for the Tofie automation system.

Quick Diagnosis #

Is Tofie Working? #

Check Linear:

  • Did Tofie respond to your comment?
  • Did the issue status change?
  • Any error messages in Linear comments?

Check n8n:

  • Go to n8n UI → Executions
  • Find execution by timestamp
  • Check for errors or timeouts

Check Coder Instance:

# SSH to Coder instance
ssh coder@coder-instance.internal

# Check worktrees
git worktree list

# Check recent logs
ls -lt ~/.claude/logs/ | head

Planning Issues #

PLAN.md Not Created #

Symptoms: Planning completes but no plan in Linear comment

Causes:

  1. Claude permission issues
  2. PLAN.md written to wrong location
  3. Claude execution timeout

Solutions:

# Check if worktree was created
git worktree list | grep "eng-1144"

# Check if .plans directory exists
ls -la /home/coder/trees/john-eng-1144/.plans/

# Check Claude logs
tail -100 ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

# Manually trigger planning
echo '{"branchName": "...", ...}' | ./planning.sh

Worktree Already Exists #

Symptoms: Error “worktree already exists” or “branch already exists”

Cause: Previous planning didn’t cleanup

Solution:

Option 1 - Reuse (scripts do this automatically):

# Scripts will reuse existing worktree
# No action needed

Option 2 - Clean start:

# Remove worktree
git worktree remove /home/coder/trees/john-eng-1144

# Remove branch
git branch -D john/eng-1144-feat-filtering

# Try again

Planning Takes Too Long #

Symptoms: Planning runs for >10 minutes

Causes:

  1. Using subagent for simple issue
  2. Very large codebase search
  3. Claude API slowness

Solutions:

# Check which script was used
# In n8n: Check "SSH Execute" node

# If using planning-subagent.sh for simple issue:
# Change to planning.sh in n8n workflow

# Check Claude execution
ps aux | grep claude
# If stuck, kill and retry

Collapsible Sections Missing #

Symptoms: PLAN.md doesn’t have +++ markers in Linear

Cause: Subagent script prompt issue

Solution:

# Check planning-subagent.sh contains collapsible instructions
grep -A 5 "CRITICAL FORMATTING REQUIREMENT" tools/local/scripts/tofie/planning-subagent.sh

# If missing, update the script
# See: tools/local/scripts/tofie/planning-subagent.sh lines 301-327

Implementation Issues #

Tests Fail After Implementation #

Symptoms: Implementation completes but mise ci fails

Cause: Claude generated code with issues

Solutions:

# Navigate to worktree
cd /home/coder/trees/john-eng-1144

# Run tests manually to see failures
mise ci

# Check specific test failures
mise test 2>&1 | grep "FAILED"

# Fix manually or use adjust.sh
echo '{"branchName": "...", "scope": "fix failing tests"}' | ./adjust.sh

Implementation Timeout #

Symptoms: n8n execution times out after 30 minutes

Causes:

  1. Very complex implementation
  2. Large number of files to modify
  3. Test suite very slow

Solutions:

# Check Claude is still running
ssh coder@coder-instance.internal
ps aux | grep claude

# If running: Let it finish, check results later in worktree
# If stuck: Kill process
pkill -f "claude.*tofie-implement"

# Break into smaller phases
# Use adjust.sh for incremental changes

Code Doesn’t Follow Project Patterns #

Symptoms: Generated code doesn’t match existing style

Cause: Claude didn’t find good examples

Solutions:

  1. Add better examples to prompt:

    • Edit /tofie-implement slash command
    • Reference specific files as patterns

  2. Use adjust.sh with specific guidance:

echo '{
  "branchName": "...",
  "scope": "refactor to match patterns in src/services/example.ts"
}' | ./adjust.sh
  1. Manual cleanup:
cd /home/coder/trees/john-eng-1144
# Make manual fixes
mise fix  # Format
git commit -m "style: align with project patterns"

PR Submission Issues #

PR Already Exists Error #

Symptoms: submit-pr.sh says PR already exists

Cause: PR was created previously (this is intentional behavior)

Solution:

# Check existing PR
gh pr list --head john/eng-1144-feat-filtering

# View PR
gh pr view 123

# If you want to recreate:
# 1. Close existing PR
gh pr close 123
# 2. Run submit-pr.sh again

PR Creation Fails #

Symptoms: gh pr create fails with error

Common Causes & Solutions:

1. Not authenticated:

# Check GitHub token
doppler secrets get GITHUB_TOKEN --plain

# Set token
export GITHUB_TOKEN=$(doppler secrets get GITHUB_TOKEN --plain)

# Test authentication
gh auth status

2. Branch not pushed:

cd /home/coder/trees/john-eng-1144

# Push branch
git push -u origin john/eng-1144-feat-filtering

# Try PR creation again

3. Invalid PR description:

# Check if PLAN.md exists
ls -la .plans/PLAN.md

# If missing, PR description may fail
# Check Claude output for errors

PR Not Created as Draft #

Symptoms: PR created as ready for review instead of draft

Cause: Script bug or manual gh pr create without --draft

Solution:

# Convert to draft
gh pr ready --undo 123

# Or via GitHub UI: Click "Convert to draft"

n8n Workflow Issues #

Webhook Not Triggering #

Symptoms: Comment in Linear but no Tofie response

Checks:

  1. Webhook signature valid:
# In n8n: Check "Webhook" node logs
# Verify signature validation passes
  1. @Tofie mention present:
# Command must include "@Tofie"
# Case-insensitive but @ required
  1. Issue in correct state:
# Planning requires: Todo or Backlog
# Implementation requires: Planned
# Check Linear issue status

Solutions:

# Test webhook manually
curl -X POST https://bonsai.app.n8n.cloud/webhook/tofie-event \
  -H "Content-Type: application/json" \
  -H "linear-signature: $(generate_signature)" \
  -d '{ "action": "create", "type": "Comment", ... }'

# Check n8n execution logs
# Go to n8n UI → Executions → Failed

SSH Connection Fails #

Symptoms: n8n can’t execute scripts on Coder instance

Causes:

  1. SSH key invalid or rotated
  2. Coder instance down
  3. Network issues

Solutions:

# Test SSH from n8n
# (Run in n8n "Code" node)
const { exec } = require('child_process');
exec('ssh coder@coder-instance.internal echo "test"', (error, stdout) => {
  if (error) throw error;
  return [{ json: { result: stdout } }];
});

# Check SSH key in n8n credentials
# Credentials → SSH → Verify key matches Coder instance

# Test from local machine
ssh -i ~/.ssh/tofie_key coder@coder-instance.internal

Script Output Not Parsed #

Symptoms: n8n shows error “Cannot parse JSON”

Cause: Script outputting non-JSON to stdout

Solution:

# Check script is using output_json function
grep "output_json" tools/local/scripts/tofie/planning.sh

# Verify logs go to stderr, not stdout
grep ">&2" tools/local/scripts/tofie/planning.sh

# Test script output
echo '{"branchName": "test", ...}' | ./planning.sh | jq empty
# Should not error if JSON is valid

Linear Integration Issues #

Status Not Updating #

Symptoms: Tofie completes but Linear status doesn’t change

Cause: Linear API credentials or GraphQL mutation error

Solution:

# Check n8n logs for Linear API errors
# Look for "issueUpdate" mutation failures

# Test Linear API manually
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(...) { success } }"}'

# Verify state IDs are correct
# Get valid state IDs:
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -d '{"query": "{ workflowStates { nodes { id name } } }"}'

Comments Not Posting #

Symptoms: Tofie completes but no comment in Linear

Cause: Comment mutation error or character encoding

Solution:

# Check comment content for special characters
# Escape quotes and newlines properly

# Test comment creation
curl -X POST https://api.linear.app/graphql \
  -H "Authorization: Bearer $LINEAR_API_KEY" \
  -d '{"query": "mutation { commentCreate(input: { issueId: \"...\", body: \"test\" }) { success } }"}'

# Check n8n "Create Comment" node logs

Git/Worktree Issues #

Worktree Won’t Remove #

Symptoms: git worktree remove fails

Cause: Files in worktree or locked

Solution:

# Force remove
git worktree remove --force /home/coder/trees/john-eng-1144

# If still fails, manually delete
rm -rf /home/coder/trees/john-eng-1144

# Clean up git metadata
git worktree prune

Branch Diverged from Main #

Symptoms: Worktree created but branch has conflicts with main

Cause: Long-running worktree, main has advanced

Solution:

cd /home/coder/trees/john-eng-1144

# Rebase on main
git fetch origin
git rebase origin/main

# If conflicts:
git status
# Fix conflicts manually
git rebase --continue

# Or start fresh:
cd /home/coder/bonsai
git worktree remove /home/coder/trees/john-eng-1144
git branch -D john/eng-1144-feat-filtering
# Re-run planning

Claude Code Issues #

Claude CLI Not Found #

Symptoms: Error “claude CLI not found”

Cause: Claude not installed or not in PATH

Solution:

# Check installation
which claude
ls -la /home/coder/.local/bin/claude

# Install if missing
curl -fsSL https://anthropic.com/claude-code-install.sh | sh

# Verify
claude --version

Permission Errors #

Symptoms: “Operation requires permission” or “Would you like to proceed?”

Cause: Wrong permission mode for script type

Solution:

For standard scripts:

# Use --permission-mode acceptEdits
claude --permission-mode acceptEdits "..."

For subagent scripts:

# Use --dangerously-skip-permissions
claude --dangerously-skip-permissions "..."

Claude Generates Invalid Code #

Symptoms: Syntax errors, import errors, type errors

Solutions:

  1. Run quality checks:
cd /home/coder/trees/john-eng-1144
mise fix  # Format
mise ci   # Check
  1. Use adjust.sh:
echo '{"branchName": "...", "scope": "fix syntax and import errors"}' | ./adjust.sh
  1. Improve prompts:
  • Edit slash commands in .cursor/commands/tofie/
  • Add better examples
  • Be more specific about patterns

Performance Issues #

Scripts Running Very Slow #

Symptoms: Normal operations take 2-3x longer

Possible Causes:

  1. Claude API slowness
  2. Coder instance overloaded
  3. Large codebase search

Solutions:

# Check Coder instance resources
ssh coder@coder-instance.internal
htop  # Check CPU/memory

# Check disk space
df -h

# Clean up old worktrees
cd /home/coder/trees
ls -lt
# Remove old ones:
cd /home/coder/bonsai
git worktree remove /home/coder/trees/old-worktree

# Clean Claude logs
rm -rf ~/.claude/logs/*.log.old

Getting Help #

Escalation Path #

  1. Check this guide - Most issues documented here
  2. Check n8n execution logs - Shows exact error
  3. Check Coder instance logs - Script execution details
  4. Post in #tofie-support - Team can help
  5. Contact DevOps - Infrastructure issues

Information to Provide #

When reporting issues, include:

**Issue**: [Brief description]

**Linear Issue**: ENG-1144
**Command**: @Tofie plan
**Timestamp**: 2025-11-03 10:30 UTC

**n8n Execution ID**: 12345
**Error Message**: [Full error]

**Logs**: [Relevant logs]

**Already Tried**: [What you've tried]

Useful Debugging Commands # 

# Check n8n workflow status
curl -X GET https://bonsai.app.n8n.cloud/api/v1/executions/12345 \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

# Check Coder instance status
ssh coder@coder-instance.internal 'uptime && df -h && free -h'

# Check Claude CLI
ssh coder@coder-instance.internal 'claude --version'

# Check recent Claude executions
ssh coder@coder-instance.internal \
  'ls -lt ~/.claude/logs/ | head -5'

# Check worktrees
ssh coder@coder-instance.internal \
  'cd /home/coder/bonsai && git worktree list'

Preventive Measures #

Regular Maintenance #

Weekly:

  • Review failed n8n executions
  • Clean up old worktrees
  • Check disk space on Coder instance

Monthly:

  • Rotate credentials (SSH keys, API tokens)
  • Update Claude CLI
  • Review and update prompts based on feedback

Best Practices #

  1. Use appropriate scripts: Standard for simple, subagent for complex
  2. Clean up worktrees: Remove after PR merged
  3. Monitor execution times: Identify slowdowns early
  4. Keep prompts updated: Improve based on results
  5. Test changes: Use test issues before production