# Debugging

## Verbose Mode

```bash
derp --verbose                    # Bare metal
make up                           # Compose (--verbose in compose file)
podman run ... derp --verbose     # Manual container
```

Shows all IRC traffic:

```
>>> NICK derp
>>> USER derp 0 * :derp IRC bot
<<< :server 001 derp :Welcome
>>> JOIN #test
```

## Log Levels

Set in `config/derp.toml`:

```toml
[logging]
level = "debug"    # debug, info, warning, error
```

Or override with `--verbose` flag (forces debug).

## Container Logs

```bash
make logs                  # podman-compose
podman logs -f derp        # direct
```

## Common Issues

### Connection refused

```
ERROR derp.irc  connection lost: [Errno 111] Connection refused
```

- Check `host` and `port` in config
- Verify TLS setting matches port (6697 = TLS, 6667 = plain)
- Test connectivity: `nc -zv <host> <port>`
- In container: ensure DNS resolution works (check `/etc/resolv.conf`)

### Nickname in use

The bot appends `_` to the nick and retries automatically:

```
<<< :server 433 * derp :Nickname is already in use
>>> NICK derp_
```

### TLS certificate errors

For self-signed certificates, set `tls_verify = false` in config:

```toml
[server]
tls_verify = false
```

### Plugin load failures

```
ERROR derp.plugin  failed to load plugin: plugins/broken.py
```

- Check plugin for syntax errors: `python -c "import py_compile; py_compile.compile('plugins/broken.py')"`
- Ensure handlers are `async def`
- Check imports (`from derp.plugin import command, event`)
- In container with mounted plugins: verify mount path and permissions

### No response to commands

- Verify `prefix` in config matches what you type
- Check that the plugin is loaded: `!plugins`
- Ensure the bot has joined the channel (check logs for `JOIN`)
- Try `!ping` first to confirm basic connectivity

### Hot-reload issues

- `!reload <plugin>` re-reads the file from disk
- In container: plugins are mounted read-only, edit on host then `!reload`
- Core plugin cannot be unloaded (but can be reloaded)
- Check logs for `loaded plugin` / `unloaded plugin` messages

### DNS plugin timeouts

- The DNS plugin uses raw UDP to the system resolver
- In container: resolver is typically `127.0.0.11` (Podman DNS)
- Fallback: `8.8.8.8` if no resolver found in `/etc/resolv.conf`

## Testing IRC Connection

```bash
# Test raw IRC (without the bot)
openssl s_client -connect irc.libera.chat:6697
# Then type: NICK testbot / USER testbot 0 * :test
```

## Inspecting State

From IRC, use these commands:

```
!plugins               # List loaded plugins + handler counts
!help <plugin>         # Show plugin description + commands
!uptime                # Bot uptime
!version               # Running version
```