View on GitHub

Troubleshooting

Having issues with BotBox or your Discord bot project?
Here are solutions to common problems.

Missing botbox.conf

If you see errors about a missing config file, run:

sh
botbox init

This will generate a new botbox.conf in your project directory.

Missing Global Config

If you see errors about missing global config, just run any BotBox command (e.g., botbox) to auto-generate it.

Legacy Config Format

If your botbox.conf looks like this (pre-2.5.0):

json
{
  "cogs": [
    {
      "name": "HelloWorld",
      "file": "helloWorld",
      "env": "development",
      "slash_commands": ["hello"],
      "prefix_commands": []
    }
  ]
}

You should upgrade to the new format:

json
{
  "cogs": [
    {
      "name": "HelloWorld",
      "file": "helloWorld",
      "env": "development",
      "slash_commands": [
        {
          "Name": "hello",
          "Scope": "guild",
          "Type": "slash",
          "Description": "Bot responds with world",
          "Args": [],
          "ReturnType": "None"
        }
      ],
      "prefix_commands": []
    }
  ]
}

To upgrade, run:

sh
botbox project upgrade

Cogs Not Loading

  • Make sure cog names in botbox.conf match the actual file names in src/cogs/.

  • Ensure the cog files exist.

  • Check that your ENVIRONMENTS variable (in .env or Doppler) includes the environment(s) for the cogs you want to load.

  • Run:

    sh
    botbox config sync

    to synchronize your config with your cog files.

Token Errors

  • Ensure your .env file exists and contains:

    env
    DISCORD_TOKEN=your-bot-token-here
DISCORD_GUILD=your-guild-id-here

  • If using Doppler, check your secrets are set in the correct project/environment.

Update Issues

If automatic updates fail, try:

sh
botbox update

botbox update installs with go install, so it needs Go on your machine. Homebrew installs update with brew upgrade botbox, and prebuilt binaries are replaced by hand from the releases page.

If the update reports that it installed to one path while the botbox you are running lives at another, you have two copies installed. Check your PATH order or delete the older copy.

Two Versions Installed

Run which -a botbox to see every copy on your PATH. A Homebrew install at /opt/homebrew/bin/botbox and a go install copy at $(go env GOPATH)/bin/botbox can shadow each other, and whichever comes first in PATH wins.

Headless Command Fails Immediately

  • --author is required and falls back to user.default_user, so either pass the flag or run botbox config set -g user.default_user "your name".
  • --doppler-project is required when you pass --env doppler.
  • A token is required when you pass --env env, from --token or BOTBOX_TOKEN.
  • botbox remove without a cog name fails, headless mode has no list to pick from.
  • Errors go to stderr, so if a pipeline looks silent check that you are not swallowing stderr.

See Headless Mode.

Configuration Issues

  • Use botbox config list to view all current settings.
  • Use botbox config list -g for global settings.

CLI Panics or Crashes

  • Make sure you’re running the latest version (botbox update).
  • Check that your project structure is valid.

Still Stuck?

Next Steps