Files
ECC/TROUBLESHOOTING.md
T
MohammadAminDHM 6286b7c2f1 fix(opencode): address review findings T01-T15 on the V2 plugin surface
P0: spawnCommand() replaces shell:true (cmd-shim routing with /d /s /c, quoted argv, windowsVerbatimArguments); permission.ask no longer auto-approves formatter/test shell prefixes; detached spawns register the error listener before resolving.

P1: loadToolModule probes .js then .ts for dist and source layouts; V2 setup() tests via mock ctx; installer recognizes every historical plugin registration (./plugins and plugins/ecc-hooks.*) via shared isOpenCodeHookConfigRegistration(); ecc-universal ./plugins export repointed to the live dist/plugins/ecc-hooks.js; opencode.json drops the file-path plugin entry OpenCode 2.x ignores, docs updated.

P2: setup() rolls back registrations and releases the directory guard on mid-setup failure; prettier non-zero exits reported as warn; subscription errors discriminated against abort; disposals awaited without unhandled rejections; windowsHide on all spawns; TROUBLESHOOTING curl passes location[directory].

Tests: opencode-plugin-hooks 22/22 (new T01/T02/T03/T05/T10/T11/T13/T14 coverage), build-opencode 11/11 (new T08 export test), hook-consent 12/12, install-executor 26/26, install-lifecycle 73/73, plugin-manifest 71/71.
2026-11-03 18:59:18 +03:30

16 KiB

Troubleshooting Guide

Common issues and solutions for ECC plugin.

Table of Contents


Memory & Context Issues

Context Window Overflow

Symptom: "Context too long" errors or incomplete responses

Causes:

  • Large file uploads exceeding token limits
  • Accumulated conversation history
  • Multiple large tool outputs in single session

Solutions:

# 1. Clear conversation history and start fresh
# Use Claude Code: "New Chat" or Cmd/Ctrl+Shift+N

# 2. Reduce file size before analysis
head -n 100 large-file.log > sample.log

# 3. Use streaming for large outputs
head -n 50 large-file.txt

# 4. Split tasks into smaller chunks
# Instead of: "Analyze all 50 files"
# Use: "Analyze files in src/components/ directory"

Memory Persistence Failures

Symptom: Agent doesn't remember previous context or observations

Causes:

  • Disabled continuous-learning hooks
  • Corrupted observation files
  • Project detection failures

Solutions:

# Check if observations are being recorded
ls ~/.claude/homunculus/projects/*/observations.jsonl

# Find the current project's hash id
python3 - <<'PY'
import json, os
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
with open(registry_path) as f:
    registry = json.load(f)
for project_id, meta in registry.items():
    if meta.get("root") == os.getcwd():
        print(project_id)
        break
else:
    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
PY

# View recent observations for that project
tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl

# Back up a corrupted observations file before recreating it
mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)

# Verify hooks are enabled
grep -r "observe" ~/.claude/settings.json

Agent Harness Failures

Agent Not Found

Symptom: "Agent not loaded" or "Unknown agent" errors

Causes:

  • Plugin not installed correctly
  • Agent path misconfiguration
  • Marketplace vs manual install mismatch

Solutions:

# Check plugin installation
ls ~/.claude/plugins/cache/

# Verify agent exists (marketplace install)
ls ~/.claude/plugins/cache/*/agents/

# For manual install, agents should be in:
ls ~/.claude/agents/  # Custom agents only

# Reload plugin
# Claude Code → Settings → Extensions → Reload

Workflow Execution Hangs

Symptom: Agent starts but never completes

Causes:

  • Infinite loops in agent logic
  • Blocked on user input
  • Network timeout waiting for API

Solutions:

# 1. Check for stuck processes
ps aux | grep claude

# 2. Enable debug mode
export CLAUDE_DEBUG=1

# 3. Set shorter timeouts
export CLAUDE_TIMEOUT=30

# 4. Check network connectivity
curl -I https://api.anthropic.com

Tool Use Errors

Symptom: "Tool execution failed" or permission denied

Causes:

  • Missing dependencies (npm, python, etc.)
  • Insufficient file permissions
  • Path not found

Solutions:

# Verify required tools are installed
which node python3 npm git

# Fix permissions on hook scripts
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh

# Check PATH includes necessary binaries
echo $PATH

Hook & Workflow Errors

Hooks Not Firing

Symptom: Pre/post hooks don't execute

Causes:

  • Hooks not registered in settings.json
  • Invalid hook syntax
  • Hook script not executable

Solutions:

# Check hooks are registered
grep -A 10 '"hooks"' ~/.claude/settings.json

# Verify hook files exist and are executable
ls -la ~/.claude/plugins/cache/*/hooks/

# Test hook manually
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'

# Re-register hooks (if using plugin)
# Disable and re-enable plugin in Claude Code settings

Python/Node Version Mismatches

Symptom: "python3 not found" or "node: command not found"

Causes:

  • Missing Python/Node installation
  • PATH not configured
  • Wrong Python version (Windows)

Solutions:

# Install Python 3 (if missing)
# macOS: brew install python3
# Ubuntu: sudo apt install python3
# Windows: Download from python.org

# Install Node.js (if missing)
# macOS: brew install node
# Ubuntu: sudo apt install nodejs npm
# Windows: Download from nodejs.org

# Verify installations
python3 --version
node --version
npm --version

# Windows: Ensure python (not python3) works
python --version

Dev Server Blocker False Positives

Symptom: Hook blocks legitimate commands mentioning "dev"

Causes:

  • Heredoc content triggering pattern match
  • Non-dev commands with "dev" in arguments

Solutions:

# This is fixed in v1.8.0+ (PR #371)
# Upgrade plugin to latest version

# Workaround: Wrap dev servers in tmux
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev

# Disable hook temporarily if needed
# Edit ~/.claude/settings.json and remove pre-bash hook

Installation & Setup

Plugin Not Loading

Symptom: Plugin features unavailable after install

Causes:

  • Marketplace cache not updated
  • Claude Code version incompatibility
  • Corrupted plugin files
  • Local Claude setup was wiped or reset

Solutions:

# First inspect what ECC still knows about this machine
ecc list-installed
ecc doctor
ecc repair

# Only reinstall if doctor/repair cannot restore the missing files

# Inspect the plugin cache before changing it
ls -la ~/.claude/plugins/cache/

# Back up the plugin cache instead of deleting it in place
mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
mkdir -p ~/.claude/plugins/cache

# Reinstall from marketplace
# Claude Code → Extensions → ECC → Uninstall
# Then reinstall from marketplace

# If the issue is marketplace/account access, use ECC Tools billing/account recovery separately; do not use reinstall as a proxy for account recovery

# Check Claude Code version
claude --version
# Requires Claude Code 2.0+

# Manual install (if marketplace fails)
git clone https://github.com/affaan-m/ECC.git
cp -r ECC ~/.claude/plugins/ecc

Package Manager Detection Fails

Symptom: Wrong package manager used (npm instead of pnpm)

Causes:

  • No lock file present
  • CLAUDE_PACKAGE_MANAGER not set
  • Multiple lock files confusing detection

Solutions:

# Set preferred package manager globally
export CLAUDE_PACKAGE_MANAGER=pnpm
# Add to ~/.bashrc or ~/.zshrc

# Or set per-project
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json

# Or use package.json field
npm pkg set packageManager="pnpm@8.15.0"

# Warning: removing lock files can change installed dependency versions.
# Commit or back up the lock file first, then run a fresh install and re-run CI.
# Only do this when intentionally switching package managers.
rm package-lock.json  # If using pnpm/yarn/bun

OpenCode Fails to Start on Termux/Android

Symptom: Changed-files tracking silently stops working (a one-time [ECC] changed-files tracking disabled warning appears in the OpenCode logs), or (on older versions) opencode crashes on startup entirely with a Bun ResolveMessage, e.g.:

ResolveMessage: Cannot find module '../plugins/lib/changed-files-store.js' from '.../.opencode/tools/changed-files.ts'

Causes:

  • The ~/.opencode install is missing or incomplete for this machine — usually tools/ and plugins/ are present but plugins/lib/ never finished copying (an interrupted install, or a storage/permission hiccup that's more common on Android's filesystem). Both the changed-files tool and the ecc-hooks plugin depend on plugins/lib/changed-files-store.js; since ecc-hooks.ts is OpenCode's plugin entry point (loaded once at session startup, before tools/index.ts's barrel file), a missing dependency there used to crash the entire OpenCode session before any hooks could load — not just the one tool.

Solutions:

# From the ECC repo, check for and repair missing/incomplete managed files
ecc doctor --target opencode
ecc repair --target opencode

# If that reports no drift but plugins/ is still missing on the device,
# re-run the ECC installer for the opencode target

Note: If you're also seeing ProviderModelNotFoundError: Model not found: openai/gpt-5.5 referencing ~/.config/opencode/oh-my-opencode-slim.json, that file belongs to the third-party oh-my-opencode-slim plugin, not ECC — ECC never writes to ~/.config/opencode/. Fix the model prefix (opencode/... instead of openai/...) there, or file it against that project.

OpenCode 2.x: PluginModule.LoadError and red "Duplicate plugin ID" entries

Symptoms (two distinct failures, often in sequence):

  1. Red startup banner / log lines:

    PluginModule.LoadError: Plugin must export a default definition with an id and
    an effect or setup function. (cause: SchemaError(Expected object at ["default"]))
    

    reported against plugins/ecc-hooks.ts (global or project .opencode/plugins/).

  2. After a first fix attempt, the TUI plugins panel shows ecc-hooks multiple times with red entries reading Duplicate plugin ID: ecc-hooks, even though the hooks themselves are working.

Causes:

  • V1 plugin on a V2 runtime. OpenCode 1.x plugins default-export an async function returning a keyed hook map. OpenCode 2.x requires a definition object { id, setup(ctx) } and does not run V1 implementations (see migrate-v1). Cause A produces the Expected object at ["default"] schema error.
  • Duplicate registration. OpenCode 2.x loads plugins by directory discovery: every root-level file in a plugins directory is a separate entry. If index.ts re-exports the same definition as ecc-hooks.ts, the id ecc-hooks registers twice; all but the first entry are marked failed: Duplicate plugin ID. A copy of the same file in both the global config plugins dir and the project .opencode/plugins/ compounds it. Note that the plugin config array does not accept file paths — an entry like "./plugins/ecc-hooks.ts" logs "configured plugin path must be a directory" and is skipped (verified against OpenCode 2.2.5's config/plugin/source.ts), so it cannot pin or dedupe entries.

Fix layout (current design):

  • .opencode/plugins/ecc-hooks.ts is the only file carrying hook logic. V1 → V2 registration mapping: tool.execute.before/after → ctx.tool.hook(...), shell.env → ctx.shell.hook("create.before", ...), permission.ask → ctx.permission.hook("evaluate", ...) (mutate event.effect), keyed event handlers (file.edited, session:*, todo.updated) → ctx.event.subscribe() filtered on event.type.
  • opencode.json carries no plugin entry for the hooks file. OpenCode 2.x discovers plugins/ecc-hooks.ts from the plugins directory; a configured file path would be ignored with a warning anyway.
  • plugins/index.ts is an inert stub with the distinct id ecc-hooks-entry. Never make it re-export the real definition: that is exactly what triggers the duplicate-id failures. It must keep a default export with an id + setup (a plain non-plugin module in a loaded directory would throw the schema error again), and it must remain present on disk for the install/uninstall plans. Module consumers of the published package get the live plugin through the ecc-universal/plugins export, which maps to dist/plugins/ecc-hooks.js.

Diagnosing (do this before editing anything):

  1. Read the server log, and check the run= id and timestamp of every error line — TUI banners survive from a process that predates your fix, so match errors against the current run only:

    ~/.local/share/opencode/log/opencode.log   # Windows, Linux, Termux
    
  2. Ignore unrelated network noise when triaging plugins: Failed to fetch models.dev, failed to sync GitHub Copilot models: 403, and update check failed are connectivity/auth issues, not hook failures.

  3. Query the live plugin table — this is the ground truth behind the TUI panel. The server port comes from opencode service status; credentials are Basic auth with the password field of ~/.config/opencode/service.json. /api/plugin is location-scoped: pass the affected project directory as location[directory], otherwise you inspect the service's default location and can miss the failures you are chasing (a location with no live session may report no entries at all):

    curl -s -u "opencode:$(sed -n 's/.*"password": "\(.*\)".*/\1/p' ~/.config/opencode/service.json)" \
      --get "http://127.0.0.1:<port>/api/plugin" \
      --data-urlencode "location[directory]=/path/to/affected/project" \
      | jq '[.data[] | select(.state.status != "active")]'
    
  4. opencode plugin list shows each registered entry with its source path. The same id appearing from two-plus sources predicts a duplicate-ID rejection.

Environment-variable note: ECC_HOOK_PROFILE / ECC_DISABLED_HOOKS are read once at plugin setup. On Windows, setx affects only new processes, and a service restarted from a terminal that predates the setx still inherits the stale environment block — restart from a freshly opened terminal.


Performance Issues

Slow Response Times

Symptom: Agent takes 30+ seconds to respond

Causes:

  • Large observation files
  • Too many active hooks
  • Network latency to API

Solutions:

# Archive large observations instead of deleting them
archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
mkdir -p "$archive_dir"
find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
  for file do
    base=$(basename "$(dirname "$file")")
    gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
    : > "$file"
  done
' sh {} +

# Disable unused hooks temporarily
# Edit ~/.claude/settings.json

# Keep active observation files small
# Large archives should live under ~/.claude/homunculus/archive/

High CPU Usage

Symptom: Claude Code consuming 100% CPU

Causes:

  • Infinite observation loops
  • File watching on large directories
  • Memory leaks in hooks

Solutions:

# Check for runaway processes
top -o cpu | grep claude

# Disable continuous learning temporarily
touch ~/.claude/homunculus/disabled

# Restart Claude Code
# Cmd/Ctrl+Q then reopen

# Check observation file size
du -sh ~/.claude/homunculus/*/

Common Error Messages

"EACCES: permission denied"

# Fix hook permissions
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;

# Fix observation directory permissions
chmod -R u+rwX,go+rX ~/.claude/homunculus

"MODULE_NOT_FOUND"

# Install plugin dependencies
# Replace <version> with the version from `claude plugin list`, for example 2.2.3
cd "$HOME/.claude/plugins/cache/ecc/ecc/<version>"
npm install

# Or for manual install
cd ~/.claude/plugins/ecc
npm install

"spawn UNKNOWN"

# Windows-specific: Ensure scripts use correct line endings
# Convert CRLF to LF
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;

# Or install dos2unix
# macOS: brew install dos2unix
# Ubuntu: sudo apt install dos2unix

Getting Help

If you're still experiencing issues:

  1. Check GitHub Issues: github.com/affaan-m/ECC/issues
  2. Enable Debug Logging:
    export CLAUDE_DEBUG=1
    export CLAUDE_LOG_LEVEL=debug
    
  3. Collect Diagnostic Info:
    claude --version
    node --version
    python3 --version
    echo $CLAUDE_PACKAGE_MANAGER
    ls -la ~/.claude/plugins/cache/
    
  4. Open an Issue: Include debug logs, error messages, and diagnostic info