Debugging

Robo.js provides built-in tools for debugging your bot, including test server scoping, a /dev command, and structured logging.

Test Server

Set DISCORD_GUILD_ID in your environment variables to scope command registration to a single server during development. Guild-scoped commands update instantly, while global commands can take up to an hour to propagate.

import type { DiscordConfig } from '@robojs/discordjs'

export default {
	testServers: [process.env.DISCORD_GUILD_ID]
} satisfies DiscordConfig

export default {
	testServers: [process.env.DISCORD_GUILD_ID]
}

This keeps development commands out of production servers and provides immediate feedback when iterating on command changes.

The /dev Command

A built-in /dev command is available when running in development mode. It displays uptime, memory usage, registered commands, loaded plugins, and recent logs directly in Discord. This command does not appear in production.

Logging

Use the logger from robo.js/logger.js for structured log output. Log levels control verbosity and can be configured per environment.

import { logger } from 'robo.js/logger.js'

export default () => {
	logger.info('Command executed')
	logger.debug('Processing data...')
	return 'Done!'
}

import { logger } from 'robo.js/logger.js'

export default () => {
	logger.info('Command executed')
	logger.debug('Processing data...')
	return 'Done!'
}

Forked Loggers

Create named logger instances with logger.fork(). This adds a prefix to all log output, making it easier to filter logs by source. Forked loggers are useful for both plugin authors and large bots where different parts of the application need to stand out in logs (e.g., logger.fork('payments'), logger.fork('auth')).

import { logger } from 'robo.js/logger.js'

export const paymentLogger = logger.fork('payments')
paymentLogger.info('Processing refund')
// Output: [payments] Processing refund

import { logger } from 'robo.js/logger.js'

export const paymentLogger = logger.fork('payments')
paymentLogger.info('Processing refund')
// Output: [payments] Processing refund

Error Handling

Always use try/catch with async operations inside handlers. Unhandled errors in event handlers can cause unexpected behavior or crash your bot.

import { logger } from 'robo.js/logger.js'

export default async () => {
	try {
		const data = await fetchExternalApi()
		return `Result: ${data}`
	} catch (error) {
		logger.error('API call failed:', error)
		return 'Something went wrong.'
	}
}

import { logger } from 'robo.js/logger.js'

export default async () => {
	try {
		const data = await fetchExternalApi()
		return `Result: ${data}`
	} catch (error) {
		logger.error('API call failed:', error)
		return 'Something went wrong.'
	}
}

Debug Channel

Set the DISCORD_DEBUG_CHANNEL_ID environment variable to forward background errors to a specific Discord channel. When configured, Sage sends error details including stack traces and context to this channel, making it easier to monitor issues in production without checking server logs.

Using the Debug Channel Effectively

1. Create a private channel in your server (e.g., #bot-errors) visible only to developers.
2. Copy the channel ID (enable Developer Mode in Discord settings, then right-click the channel).
3. Add it to your .env file:

# .env
DISCORD_DEBUG_CHANNEL_ID="your_channel_id"

Errors that occur outside of command or event handlers (background tasks, unhandled rejections) are forwarded here with full stack traces and a time-locked log snapshot showing what happened leading up to the error.

Common Errors and Fixes

Command Registration Issues

When commands do not appear in Discord or appear outdated, the issue is usually related to registration caching.

Force Re-registration

Robo.js uses hash caching to detect command changes and only re-registers when files have changed. If commands are not updating or you see stale commands that should have been removed, force a full re-registration:

npx robo build --force

The --force flag bypasses the hash cache, re-registers all commands with Discord, and cleans up commands that no longer exist in your src/commands/ directory.

Guild vs Global Commands

Guild-scoped commands (when DISCORD_GUILD_ID is set) update instantly. Global commands can take up to an hour to propagate across all servers. During development, always use guild-scoped registration for fast feedback.

Mock Server

For automated testing, see Mock Server which simulates Discord's API locally. This lets you test commands, events, and interactions without a live Discord connection.

Next Steps