IRC-kosmi-relay/IRC_TROUBLESHOOTING.md

# IRC → Kosmi Relay Troubleshooting

**Date**: 2025-10-31  
**Issue**: Messages from Kosmi → IRC work perfectly. Messages from IRC → Kosmi do NOT work.

## Current Status

✅ **Working**: Kosmi → IRC  
❌ **Not Working**: IRC → Kosmi

## Symptoms

1. **No IRC message logs**: The bridge shows ZERO indication that IRC messages are being received
2. **No debug output**: Even with `Debug=true` and `DebugLevel=1`, we see NO IRC protocol messages in logs
3. **Only Kosmi messages appear**: Logs only show Kosmi→IRC relay activity

## What We Know Works

- **IRC Connection**: `Connection succeeded` message appears
- **Channel Join Request**: `irc.libera: joining #cottongin` message appears
- **Kosmi → IRC**: Messages from Kosmi successfully appear in IRC
- **Bridge Startup**: Gateway starts successfully

## What's Missing

- **No PRIVMSG logs**: The `handlePrivMsg` function should log `== Receiving PRIVMSG` but doesn't
- **No debug protocol messages**: With `DebugLevel=1` we should see ALL IRC protocol traffic
- **No JOIN confirmation**: We never see confirmation that the bot actually joined the channel

## Possible Causes

### 1. Bot Not Actually in Channel
**Symptom**: The bot might not have successfully joined #cottongin  
**How to check**: Look at the user list in #cottongin - is `kosmi-relay` there?  
**Why**: IRC servers can silently fail channel joins for various reasons (invite-only, banned, etc.)

### 2. Channel Name Mismatch
**Current config**: Channel is `#cottongin`  
**Check**: Is the channel name exactly correct? (case-sensitive, # prefix?)

### 3. Message Handler Not Registered
**Possible issue**: The PRIVMSG handler might not be properly registered  
**Evidence**: No debug logs at all from IRC message handling

### 4. IRC Bridge Not Receiving Events
**Possible issue**: The `girc` IRC library might not be firing events  
**Evidence**: Zero IRC protocol messages in logs even with DebugLevel=1

## Configuration

Current `matterbridge.toml` IRC section:
```toml
[irc.libera]
Server="irc.zeronode.net:6697"
Nick="kosmi-relay"
DebugLevel=1
UseTLS=true
SkipTLSVerify=false
Channels=["#cottongin"]
Debug=true
```

Current gateway configuration:
```toml
[[gateway.inout]]
account="irc.libera"
channel="#cottongin"
```

## Diagnostic Steps

### Step 1: Verify Bot is in Channel ✋ **NEEDS USER CONFIRMATION**

**Action Required**: Check if `kosmi-relay` appears in the #cottongin user list

If NO:
- Bot failed to join (permissions, invite-only, ban, etc.)
- Need to check IRC server response

If YES:
- Bot is in channel but not receiving messages
- Proceed to Step 2

### Step 2: Check IRC Server Responses

The lack of debug output suggests the IRC library isn't logging anything. This could mean:
- The IRC event handlers aren't being called
- The debug configuration isn't being applied correctly
- There's a deeper issue with the IRC bridge initialization

### Step 3: Test with Manual IRC Message

**Request**: Please send a test message in #cottongin IRC channel  
**Watch for**: Any log output mentioning IRC, PRIVMSG, or message reception

### Step 4: Check for Silent Errors

Look for any errors that might be silently dropped:
```bash
docker-compose logs | grep -iE "(error|fail|warn)" | grep -i irc
```

## Code Analysis

### How IRC Messages Should Flow

1. IRC server sends PRIVMSG to bot
2. `girc` library receives it and fires event
3. `handlePrivMsg` function is called (line 193 of handlers.go)
4. `skipPrivMsg` check (line 194) - returns true if message is from bot itself
5. If not skipped, logs: `== Receiving PRIVMSG: ...` (line 205)
6. Creates `config.Message` (line 198-203)
7. Sends to gateway via `b.Remote <- rmsg` (line 255)
8. Gateway routes to Kosmi bridge
9. Kosmi `Send` method is called (line 106 of kosmi.go)
10. Message sent via `SendMessage` to Kosmi WebSocket

### Where the Flow is Breaking

The logs show **NOTHING** from steps 1-7. This means:
- Either the message never reaches the bot
- Or the event handler isn't firing
- Or messages are being filtered before logging

## Next Steps

1. ✋ **USER**: Confirm if `kosmi-relay` bot is visible in #cottongin user list
2. ✋ **USER**: Send a test message in IRC: "TEST FROM IRC TO KOSMI"
3. Check logs for any indication of message reception
4. If still nothing, we may need to:
   - Add explicit logging to the IRC bridge code
   - Rebuild the Docker image with instrumentation
   - Check if there's a gateway routing issue

## Temporary Workaround

None available - this is core functionality.

## Related Files

- `bridge/irc/handlers.go` - IRC message handling
- `bridge/irc/irc.go` - IRC bridge main logic
- `bridge/kosmi/kosmi.go` - Kosmi bridge (Send method)
- `matterbridge.toml` - Configuration
- `gateway/router.go` - Message routing between bridges

## Status

🔴 **BLOCKED**: Waiting for user confirmation on whether bot is in IRC channel