Files

3.4 KiB

Debugging

Handler Not Triggering

Most common issue. Check in order:

1. Webhook URL Correct?

# Your bot should log incoming requests
curl -X POST https://your-webhook-url/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

2. Tunnel Running? (local dev)

# Tailscale
tailscale funnel status

# ngrok
curl http://127.0.0.1:4040/api/tunnels

3. Bot Added to Channel?

Bot must be:

  • Installed in the Space (Settings → Integrations)
  • Added to the specific channel (Channel Settings → Integrations)

4. Message Forwarding Mode?

In Developer Portal:

  • "Mentions Only" = only @bot messages
  • "All Messages" = everything (required for onTip)

5. Slash Command Registered?

Must be in commands array passed to makeTownsBot:

const commands = [
  { name: 'mycommand', description: 'Does something' }
] as const satisfies BotCommand[]

const bot = await makeTownsBot(creds, secret, { commands })

Add Request Logging

const bot = await makeTownsBot(
  process.env.APP_PRIVATE_DATA!,
  process.env.JWT_SECRET!,
  { commands }
)

// Log all incoming events
bot.onMessage(async (handler, event) => {
  console.log('[onMessage]', {
    userId: event.userId,
    channelId: event.channelId,
    message: event.message.slice(0, 100),
    isMentioned: event.isMentioned
  })
  // ... rest of handler
})

bot.onSlashCommand('*', async (handler, event) => {
  console.log('[onSlashCommand]', {
    command: event.command,
    args: event.args,
    userId: event.userId
  })
})

Common Error Messages

Error Cause Fix
JWT verification failed Wrong JWT_SECRET Match secret in Developer Portal
insufficient funds for gas Empty gas wallet Fund bot.viem.account.address
Invalid APP_PRIVATE_DATA Malformed credentials Re-copy from Developer Portal
ECONNREFUSED on RPC Bad RPC URL or rate limited Use dedicated RPC (Alchemy/Infura)
nonce too low Concurrent transactions Add transaction queue or retry logic

Verify Webhook Connectivity

import { Hono } from 'hono'

const app = new Hono()

app.get('/health', (c) => c.json({
  status: 'ok',
  timestamp: new Date().toISOString(),
  gasWallet: bot.viem.account.address
}))

// Test from outside:
// curl https://your-webhook-url/health

Debug Transaction Failures

import { waitForTransactionReceipt } from 'viem/actions'

try {
  const hash = await execute(bot.viem, { /* ... */ })
  console.log('TX submitted:', hash)

  const receipt = await waitForTransactionReceipt(bot.viem, { hash })
  console.log('TX result:', {
    status: receipt.status,
    gasUsed: receipt.gasUsed.toString(),
    blockNumber: receipt.blockNumber
  })

  if (receipt.status !== 'success') {
    console.error('TX reverted. Check on basescan:',
      'https://basescan.org/tx/' + hash)
  }
} catch (err) {
  console.error('TX failed:', err.message)
  // Common: insufficient funds, nonce issues, contract revert
}

Check Gas Wallet Balance

import { formatEther } from 'viem'

const balance = await bot.viem.getBalance({
  address: bot.viem.account.address
})

console.log('Gas wallet balance:', formatEther(balance), 'ETH')

if (balance === 0n) {
  console.error('WARNING: Gas wallet is empty!')
  console.error('Fund this address:', bot.viem.account.address)
}