Troubleshooting

Fix common problems with the Discord bot.

Finding the bot's logs #

Most problems show up in the bot's logs. Open the Cloudflare dashboard, go to Workers & Pages → your Worker → Logs, or stream them live from your bot's folder:

bash

npx wrangler tail

When the bot can't get an answer from your docs site, it logs a line like this:

text

CAD search failed: CAD_NOT_FOUND (https://docs.example.com/api/search?q=eggs: HTTP 404)

The code in capitals says what went wrong. The address shows exactly what the bot asked for.

"The application didn't respond in time" #

Discord shows this when it gets no usable reply within three seconds.

Check the Interactions Endpoint URL. It must be your Worker's current URL. Discord verifies it when you save.
Check the bot is running. If there are no log entries when you use a command, Discord isn't reaching the Worker.
Update the bot. Versions before 1.1.3 sent a reply Discord rejected whenever your site's home page was among the search results. See Updates and upgrading .

Every search fails #

Look for these codes in the logs:

Code	Meaning	Fix
`CAD_BLOCKED`	Your docs site is a Worker in the same Cloudflare account, and Cloudflare blocked the request (error 1042).	Add `"compatibility_flags": ["global_fetch_strictly_public"]` to the bot's `wrangler.jsonc` and redeploy.
`CAD_NOT_FOUND`	The site answered, but has no page at that address.	Check that `CAD_BASE_URL` is the site's root, not a page or the main website, and that the site has the API routes.
`CAD_UNREACHABLE`	The site didn't respond within ten seconds, or its address doesn't exist.	Check `CAD_BASE_URL` and that the site is online.
`CAD_HTTP_500` and similar	The site returned an error.	Check the docs site's own logs.
`CAD_INVALID_RESPONSE`	The site returned something that isn't JSON, such as an HTML page.	`CAD_BASE_URL` probably points at a site that isn't running ctrl alt doc.

Commands are missing or out of date #

The bot registers its own commands, which needs the DISCORD_TOKEN secret.

Check the secret is set: npx wrangler secret list.
Discord invalidates a token when you reset it in the Developer Portal. If you reset it, set the new one with npx wrangler secret put DISCORD_TOKEN.
After fixing the token, use any command, or wait up to an hour, for the bot to register its commands.
Discord caches the command list. Press Ctrl+R (or Cmd+R on a Mac) in Discord to reload it.

Duplicate commands #

If every command appears twice, one copy is registered to your server and the other to every server. That happens after moving from an older setup that used DISCORD_GUILD_ID.

Remove the server-only copies by running this with your bot's details. It asks for the token without showing it:

bash

read -rsp "Bot token: " DISCORD_TOKEN && echo
curl -X PUT "https://discord.com/api/v10/applications/YOUR_APPLICATION_ID/guilds/YOUR_SERVER_ID/commands" \
  -H "Authorization: Bot $DISCORD_TOKEN" -H "Content-Type: application/json" -d '[]'
unset DISCORD_TOKEN

A 401 response means the token is wrong, usually because it was reset. Use the current token.

If the two copies come from different bots, Discord shows each bot's name beside its commands. Remove the bot you no longer need from the server.

Section text looks wrong #

"Open the page to read this section." The bot couldn't find that heading in the page. The page may have changed since the suggestion was shown. Try again.
Plain formatting, such as code without highlighting. Your docs site is older than 1.0.7 and only sends rendered HTML. See Preparing your docs site .
Headings shown as large text, or stray # characters. This was fixed in 1.1.2. Update the bot.

A page is never found #

If /ask doesn't find a page you know exists, try the same search on your docs site. The bot uses the site's own search, so both give the same results. To improve them, see Writing docs that search well .