IRC-kosmi-relay/docs/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:

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

Current gateway configuration:

[[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:

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