OpenAgentsControl/.opencode/context/openagents-repo/guides/debugging.md

Guide: Debugging Common Issues

Purpose: Troubleshooting guide for common problems

---

Quick Diagnostics

# Check system health
./scripts/registry/validate-registry.sh
./scripts/validation/validate-test-suites.sh

# Check version consistency
cat VERSION && cat package.json | jq '.version'

# Test core agents
cd evals/framework && npm run eval:sdk -- --agent=core/openagent --pattern="smoke-test.yaml"

---

Registry Issues

Registry Validation Fails

Symptoms:

ERROR: Path does not exist: .opencode/agent/core/missing.md

Diagnosis:

./scripts/registry/validate-registry.sh -v

Solutions:

1. Path doesn't exist: Remove entry or create file
2. Duplicate ID: Rename one component
3. Invalid category: Use valid category

Fix:

# Re-run auto-detect
./scripts/registry/auto-detect-components.sh --auto-add

# Validate
./scripts/registry/validate-registry.sh

---

Component Not in Registry

Symptoms:

• Component doesn't appear in ./install.sh --list
• Auto-detect doesn't find component

Diagnosis:

# Check frontmatter
head -10 .opencode/agent/{category}/{agent}.md

# Dry run auto-detect
./scripts/registry/auto-detect-components.sh --dry-run

Solutions:

1. Missing frontmatter: Add frontmatter
2. Invalid YAML: Fix YAML syntax
3. Wrong location: Move to correct directory

Fix:

# Add frontmatter
cat > .opencode/agent/{category}/{agent}.md << 'EOF'
---
description: "Brief description"
category: "category"
type: "agent"
---

# Agent Content
EOF

# Re-run auto-detect
./scripts/registry/auto-detect-components.sh --auto-add

---

Test Failures

Approval Gate Violation

Symptoms:

✗ Approval Gate: FAIL
  Violation: Agent executed write tool without requesting approval

Diagnosis:

# Run with debug
cd evals/framework
npm run eval:sdk -- --agent={agent} --pattern="{test}" --debug

# Check session
ls -lt .tmp/sessions/ | head -5
cat .tmp/sessions/{session-id}/session.json | jq

Solution: Add approval request in agent prompt:

Before executing:
1. Present plan to user
2. Request approval
3. Execute after approval

---

Context Loading Violation

Symptoms:

✗ Context Loading: FAIL
  Violation: Agent executed write tool without loading required context

Diagnosis:

# Check what context was loaded
cat .tmp/sessions/{session-id}/events.json | jq '.[] | select(.type == "context_load")'

Solution: Add context loading in agent prompt:

Before implementing:
1. Load core/standards/code-quality.md
2. Apply standards to implementation

---

Tool Usage Violation

Symptoms:

✗ Tool Usage: FAIL
  Violation: Agent used bash tool for reading file instead of read tool

Diagnosis:

# Check tool usage
cat .tmp/sessions/{session-id}/events.json | jq '.[] | select(.type == "tool_call")'

Solution: Update agent to use correct tools:

• Use read instead of bash cat
• Use list instead of bash ls
• Use grep instead of bash grep

---

Install Issues

Install Script Fails

Symptoms:

ERROR: Failed to fetch registry
ERROR: Component not found

Diagnosis:

# Check dependencies
which curl jq

# Test with local registry
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list

Solutions:

1. Missing dependencies: Install curl and jq
2. Registry not found: Check registry.json exists
3. Component not found: Verify component in registry

Fix:

# Install dependencies (macOS)
brew install curl jq

# Install dependencies (Linux)
sudo apt-get install curl jq

# Test locally
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list

---

Collision Handling

Symptoms:

File exists: .opencode/agent/core/openagent.md

Solutions:

1. Skip: Keep existing file
2. Overwrite: Replace with new file
3. Backup: Backup existing, install new

Fix:

# Skip all collisions
./install.sh developer --skip-existing

# Overwrite all collisions
./install.sh developer --force

# Backup all collisions
./install.sh developer --backup

---

Path Resolution Issues

Agent Not Found

Symptoms:

ERROR: Agent not found: development/frontend-specialist

Diagnosis:

# Check file exists
ls -la .opencode/agent/development/frontend-specialist.md

# Check registry
cat registry.json | jq '.components.agents[] | select(.id == "frontend-specialist")'

Solutions:

1. File doesn't exist: Create file
2. Wrong path: Fix path in registry
3. Not in registry: Run auto-detect

Fix:

# Re-run auto-detect
./scripts/registry/auto-detect-components.sh --auto-add

# Validate
./scripts/registry/validate-registry.sh

---

Version Issues

Version Mismatch

Symptoms:

VERSION: 0.5.0
package.json: 0.4.0
registry.json: 0.5.0

Diagnosis:

cat VERSION
cat package.json | jq '.version'
cat registry.json | jq '.version'

Solution: Update all to same version:

echo "0.5.0" > VERSION
jq '.version = "0.5.0"' package.json > tmp && mv tmp package.json
jq '.version = "0.5.0"' registry.json > tmp && mv tmp registry.json

---

CI/CD Issues

Workflow Fails

Symptoms:

• Registry validation fails in CI
• Tests fail in CI but pass locally

Diagnosis:

# Run same commands as CI
./scripts/registry/validate-registry.sh
./scripts/validation/validate-test-suites.sh
cd evals/framework && npm run eval:sdk

Solutions:

1. Registry invalid: Fix registry
2. Tests fail: Fix tests
3. Dependencies missing: Update CI config

---

Performance Issues

Tests Timeout

Symptoms:

ERROR: Test timeout after 60000ms

Solution: Increase timeout in config.yaml:

timeout: 120000  # 2 minutes

---

Slow Auto-Detect

Symptoms: Auto-detect takes too long

Solution: Limit scope:

# Only scan specific directory
./scripts/registry/auto-detect-components.sh --path .opencode/agent/development/

---

Getting Help

Check Logs

# Session logs
ls -lt .tmp/sessions/ | head -5
cat .tmp/sessions/{session-id}/session.json | jq

# Event timeline
cat .tmp/sessions/{session-id}/events.json | jq

Run Diagnostics

# Full system check
./scripts/registry/validate-registry.sh -v
./scripts/validation/validate-test-suites.sh
cd evals/framework && npm run eval:sdk -- --agent=core/openagent

Common Commands

# Validate everything
./scripts/registry/validate-registry.sh && \
./scripts/validation/validate-test-suites.sh && \
cd evals/framework && npm run eval:sdk

# Reset and rebuild
./scripts/registry/auto-detect-components.sh --auto-add --force
./scripts/registry/validate-registry.sh

# Test installation
REGISTRY_URL="file://$(pwd)/registry.json" ./install.sh --list

---

Related Files

• Testing guide: guides/testing-agent.md
• Registry guide: guides/updating-registry.md
• Eval concepts: core-concepts/evals.md

---

Last Updated: 2025-12-10
Version: 0.5.0