How to update your Discord bot safely, with minimal downtime

Updating a bot should be boring: upload new code, restart, done. When it is not boring, it is because the update broke something nobody tested, or because two copies of the bot ended up running together. This guide gives you an update routine that keeps downtime to seconds and gives you a way back when something goes wrong.

The one rule about two copies

A Discord bot token can be used by several programs at once, and Discord will send events to all of them. So if you start a new copy of your bot before the old one has stopped, both respond to every command. Users see double replies, and anything the bot does, such as giving roles or sending warnings, happens twice.

That is why a bot cannot easily do "zero downtime" updates the way a website can. The realistic goal is a very short restart, with the old copy fully stopped first.

A safe routine

  1. Test on a staging bot. Keep a second bot with its own token and a private server. Run the new code there first, so you find mistakes before your members do. See How to create a Discord bot and keep its token safe.
  2. Back up. Copy the current code and the database file. See Creating and restoring backups.
  3. Pick a quiet time. Check when your members are least active.
  4. Upload the new code while the bot is still running. Uploading takes a while and does no harm to a running process that has already loaded its files.
  5. Install new dependencies if your packages changed.
  6. Restart once, from the panel's controls. See Starting, stopping and restarting your server.
  7. Watch the console for the "logged in" message and any errors.
  8. Test the main commands in a real server.

The actual downtime is the few seconds between stopping and the bot being ready again.

Handle shutdown gracefully

When the panel stops your bot, it sends a signal asking it to quit. If your code ignores it, the bot is killed abruptly, which can leave work half done. Handle the signal so the bot finishes what it is doing:

  • In Node.js, listen for SIGTERM and SIGINT, close the client and the database, then exit.
  • In Python, catch the cancellation, close the bot with await bot.close() and close any connections.

A clean shutdown also means the bot disconnects properly, which helps Discord clear its presence faster.

Changing slash commands

If an update adds, renames or removes commands, they have to be registered with Discord again, once. Do not do this on every start. Run a deploy script when the list changes, and use guild commands on your test server first, since they update immediately. Global commands can take longer to appear everywhere. See Slash commands vs prefix commands.

If you change what a command does, but not its name or options, there is nothing to register again.

Database changes

Changing your tables is the riskiest part of an update. Do it carefully:

  • Write the change as a migration script that can be run once.
  • Run it on a copy of your database first.
  • Make changes that old code could survive, such as adding a column rather than renaming one, if you might need to roll back.
  • Back up before running it for real. See How to use a database with your Discord bot.

Keep a way back

Before replacing files, keep the old version. Two simple ways:

  • Versioned folders. Keep each release in its own folder and point the start-up at one of them.
  • Version control. With Git, you can return to a previous version by checking out an earlier commit.

If the new version crashes, stop it, put the old code back, and restart. Then fix the problem calmly, without members waiting. If the problem is in the logs, How to read your server logs will help you find it.

Tell people

For anything that changes how the bot behaves, post a short note in your server or a changelog channel. People accept small interruptions when they are warned. For a long outage, change the bot's status to say it is updating, before you stop it.

Automating

Once your routine is stable, you can automate parts of it: a script that pulls the latest code, installs packages and restarts. Keep a person in the loop for the final restart until you trust it, and avoid auto-deploying straight from your main branch without testing. A wrong commit would update your live bot immediately.

If an update goes wrong

  1. Roll back to the old code.
  2. Check the logs for the cause.
  3. Reproduce the problem on the staging bot.
  4. Fix, and try again.

Rolling back first is always the right order, because it ends the outage before the investigation starts. If the bot keeps crashing on start, see Keep your bot online for how restarts behave.

Still stuck? Open a ticket on Discord - run /ticket in any channel, pick a department, and include your Server ID or Invoice ID so we can jump straight in.