# Debug Command

> Run the `synapse-plugin-helper:debug` workflow from the original Claude slash command. Use when the user asks to diagnose and fix common Synapse plugin issues

- Skill: `datamaker-kr/debug-command` (Agent Skill)
- Install (CLI): `npx skillmds@latest add datamaker-kr/debug-command`
- Raw SKILL.md: https://api.skillmd.com/api/skills/datamaker-kr/debug-command/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: datamaker-kr (https://skillmd.com/u/datamaker-kr)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/datamaker-kr/debug-command

---


<!-- Generated by tools/generate-agent-marketplaces.py; edit the source command or agent-plugin.yaml instead. -->

# synapse-plugin-helper:debug Command Workflow

## Codex Adaptation

- Treat the user request or explicitly supplied text as the command arguments.
- Use the available Codex file, search, terminal, and clarification capabilities that match the workflow.
- Do not depend on Claude-only slash command variables or tool names.

# Debug Synapse Plugin

Diagnose and resolve common issues with Synapse plugins.

**Arguments:** the user request or explicit arguments

## Workflow

### Step 1: Identify Problem

If error message provided in `the user request or explicit arguments`:
- Parse the error type and message
- Identify likely cause

If no specific error:
- Ask user to describe the issue
- Run diagnostic checks

### Step 2: Run Diagnostic Checks

Execute these checks in order:

#### 1. Config Validation
```bash
# Check config.yaml or synapse.yaml exists and is valid
CONFIG_FILE=config.yaml
if [ -f synapse.yaml ]; then CONFIG_FILE=synapse.yaml; fi
cat "$CONFIG_FILE"
```

Verify:
- [ ] `name` and `code` fields present
- [ ] `actions` section defined
- [ ] Entrypoints use correct format (`module:ClassName` or `module.function`)

#### 2. Entrypoint Verification
```bash
# Check entrypoint files exist
python -c "from [module] import [class]"
```

Verify:
- [ ] Module file exists
- [ ] Class/function is importable
- [ ] No syntax errors

#### 3. Dependency Check
```bash
# Verify requirements installed
pip check
pip list | grep -E "synapse|pydantic|ray"
```

Verify:
- [ ] synapse-sdk installed
- [ ] pydantic installed
- [ ] All requirements.txt packages installed

#### 4. Parameter Schema Check
```python
# Validate Pydantic models
python -c "from [module] import [ParamsClass]; print([ParamsClass].model_json_schema())"
```

### Step 3: Common Issues & Solutions

| Error | Cause | Solution |
|-------|-------|----------|
| `ModuleNotFoundError` | Missing dependency | `pip install -r requirements.txt` |
| `ImportError: cannot import` | Wrong entrypoint path | Check module.path:ClassName format |
| `ValidationError` | Invalid parameters | Check Pydantic model types |
| `RuntimeContextError` | Missing context | Ensure action receives `ctx` parameter |
| `ConfigError: invalid action` | Wrong method type | Use `job`, `task`, or `serve` |
| `Warning: config out of sync` | Entry points/types drifted | Run `synapse plugin update-config` |

### Step 4: Detailed Analysis

If automated checks don't find issue:
1. Use the **troubleshooter** agent for deeper analysis
2. Check logs with `/synapse-plugin:logs`
3. Review recent changes in config.yaml or action code

### Step 5: Provide Solution

After identifying the issue:
1. Explain the root cause
2. Provide specific fix instructions
3. Show corrected code if applicable
4. Suggest prevention measures

## Quick Fixes

**Fix import errors:**
```bash
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
```

**Fix missing synapse-sdk:**
```bash
pip install synapse-sdk
```

**Fix config.yaml formatting:**
```bash
python -c "import yaml; yaml.safe_load(open('config.yaml'))"
```

**Sync config with code:**
```bash
synapse plugin update-config
```

## Invoke Troubleshooter Agent

For complex issues, the troubleshooter agent provides:
- Deep error log analysis
- Pattern matching against known issues
- Web search for similar problems
- Step-by-step resolution guidance