Troubleshooting Guide

How to read error responses and where to look first.

How errors appear in Discord

Structra returns errors as ephemeral embeds — only visible to you. They include a plain-English description of what went wrong and, where possible, the next step to fix it.

Where to look first

  1. 1.Check bot permissions in Server Settings → Integrations → Structra
  2. 2.Run /config and check that the relevant module is fully configured
  3. 3.Check channel-level permission overwrites
  4. 4.If the error mentions a specific code (403, 429, 503), see the API Errors section below

If the bot is completely unresponsive (no error, no response), it may be offline. Check the Structra support server for status updates.

Bot Missing Permissions

Permissions

Why it happens

Structra doesn't have the required Discord permissions in the server or a specific channel.

How to fix it

  1. 1Go to Server Settings → Integrations → Structra
  2. 2Ensure these permissions are granted: Manage Channels, Manage Roles, Manage Messages, Send Messages, Embed Links, Attach Files, Read Message History, Use External Emojis, Add Reactions, Manage Threads, Create Public Threads, Moderate Members
  3. 3Check individual channel permission overwrites — a channel-level overwrite can block the bot even if server-level permissions are granted
  4. 4Move Structra's role higher in the role list if the bot can't manage members with higher roles

You Don't Have Permission to Use This

Permissions

Why it happens

The command requires a Discord permission (e.g. Manage Guild) or a configured role (e.g. ad moderator) that you don't have.

How to fix it

  1. 1Ask your server owner which role is configured for this module in /config
  2. 2Have the server owner grant you the required Discord permission, or add you to the configured manager role

Command Not Available Here

Permissions

Why it happens

Some commands only work in specific channel types. For example, /add only works inside an active ticket channel.

How to fix it

  1. 1Check the Help page to confirm where the command should be run
  2. 2Run /add and /add remove inside an active ticket channel

This Module Is Not Configured

/config

Why it happens

/config has not been completed for this feature yet.

How to fix it

  1. 1Run /config
  2. 2Navigate to the relevant module using the buttons
  3. 3Complete all required fields and save

Your previous /config settings are saved — only unconfigured modules need attention.

Setup Wizard Timed Out

/config

Why it happens

No interaction was made within the 5-minute timeout window.

How to fix it

  1. 1Run /config again — your previous settings are not lost

Channel Not Found

/config

Why it happens

A channel that was configured in /config has been deleted, renamed, or had its ID changed.

How to fix it

  1. 1Run /config and navigate to the affected module
  2. 2Reassign the channel to a valid, existing channel
  3. 3Save the updated configuration

Role Not Found

/config

Why it happens

A role configured in /config was deleted from the server.

How to fix it

  1. 1Recreate the deleted role if needed
  2. 2Run /config and navigate to the affected module
  3. 3Reassign the role and save

/template load — Confirmation Required

/template

Why it happens

This is not an error — it's a safety gate. /template load is destructive and requires explicit confirmation.

How to fix it

  1. 1Read the confirmation message carefully
  2. 2Confirm only if you intend to delete ALL existing channels and roles

/template load CANNOT be undone. If a load fails midway, some channels may already be deleted. Re-run the load or restore manually.

Template Loaded but No Roles Appeared

/template

Why it happens

A bug in earlier versions caused template loads to skip role creation.

How to fix it

  1. 1This was fixed in 2.0.1 — update to the latest version and load the template again

Template Failed with Missing Permissions

/template

Why it happens

Structra needs Manage Roles and Manage Channels, and its role must be at the top of the role hierarchy.

How to fix it

  1. 1Grant Structra the Manage Roles and Manage Channels permissions
  2. 2Move Structra's role to the top of the role list in Server Settings → Roles
  3. 3Retry the load — the bot now tells you exactly what is missing before starting

Some Channels Were Skipped During Template Load

/template

Why it happens

Usually caused by role hierarchy — Structra couldn't create or modify some channels.

How to fix it

  1. 1Check the summary Structra sends — it lists exactly what was skipped
  2. 2Move Structra's role higher in the role list
  3. 3Retry the skipped items manually

Announcement Channels Became Text Channels After Loading

/template

Why it happens

Announcement channels require Community to be enabled and cannot be created via API.

How to fix it

  1. 1No action needed — they are restored as standard text channels
  2. 2If you want announcement channels, enable Community in Server Settings and convert them manually

/approve — User Has No Pending Application

Applications

Why it happens

The user hasn't submitted an application, or it was already processed.

How to fix it

  1. 1Check the applications forum thread to confirm the user has a pending application
  2. 2Ensure you're targeting the correct user

/approve or /deny — Could Not Send DM

Applications

Why it happens

The applicant has DMs disabled or has blocked the bot.

How to fix it

  1. 1No action needed — the approval or denial still completes. The DM just won't send.

A note is posted in the ticket channel when the DM fails. Inform the applicant manually if needed.

/approve — Ticket Channel Not Found

Applications

Why it happens

The ticket channel associated with this application was manually deleted.

How to fix it

  1. 1Locate the application in the forum thread
  2. 2Run /approve from the forum thread directly if possible
  3. 3If not, re-open the application process for the user

/add — Must Be Used in a Ticket Channel

Tickets

Why it happens

/add was run in a regular channel, not inside an active ticket.

How to fix it

  1. 1Navigate to an active ticket channel and run /add from there

/add remove — Cannot Remove the Ticket Owner

Tickets

Why it happens

Ticket owners cannot be removed from their own ticket — this is by design.

How to fix it

  1. 1Close the ticket instead if you need to remove the owner's access

/roleall — Missing ManageRoles Permission

Utilities

Why it happens

Structra doesn't have the Manage Roles permission in Server Settings.

How to fix it

  1. 1Go to Server Settings → Integrations → Structra
  2. 2Enable the Manage Roles permission

/roleall — Progress Bar Stalled

Utilities

Why it happens

Processing large servers takes time. /roleall processes members in batches of 5 with rate-limit delays.

How to fix it

  1. 1Let it complete — this is expected behavior on large servers. Do not cancel mid-run.

/roleall — Some Members Skipped

Utilities

Why it happens

Members with roles higher than Structra's highest role cannot have roles assigned by the bot.

How to fix it

  1. 1Go to Server Settings → Roles
  2. 2Drag Structra's role to the top of the role list (above the roles you're trying to assign)

/stats — Charts Not Generating

/stats

Why it happens

A dependency issue with the chart rendering environment.

How to fix it

  1. 1Check that the bot's environment has all required packages installed
  2. 2Restart the bot and try again
  3. 3If the issue persists, report it in the Structra support server

/stats — Invite Chart Shows 0

/stats

Why it happens

The invite cache may not have seeded correctly after bot startup.

How to fix it

  1. 1Restart the bot — the invite cache re-seeds on the ready event
  2. 2Invites created before the bot joined won't be tracked until a restart

/giveaway — No Active Giveaways

Giveaways

Why it happens

There are no running giveaways in this server.

How to fix it

  1. 1Use /giveaway create or open /giveaway-hub to start one

/giveaway reroll — Giveaway Still Active

Giveaways

Why it happens

/giveaway reroll can only be used after a giveaway has ended.

How to fix it

  1. 1End the giveaway first with /giveaway end, then reroll

/giveaway — Winners Not DM'd

Giveaways

Why it happens

Winners have their DMs disabled.

How to fix it

  1. 1Check the giveaway log channel for winner names
  2. 2Announce winners manually in the server

/giveaway — Timer Didn't Fire on Time

Giveaways

Why it happens

The bot was offline when the giveaway was scheduled to end.

How to fix it

  1. 1No action needed — when the bot restarts, it reschedules the timer and ends the giveaway immediately if the end time has passed.

/sticky — Sticky Not Reposting

Sticky

Why it happens

The message count delay hasn't been reached yet, or the delay is set very high.

How to fix it

  1. 1Check delay settings in /config → Sticky Messages or /sticky-manager
  2. 2The sticky only reposts after X new messages in the channel — confirm the delay value makes sense for your channel's activity

/sticky — Sticky Deleted Itself

Sticky

Why it happens

Structra lost Manage Messages permission in that channel, preventing it from deleting and reposting the sticky.

How to fix it

  1. 1Re-grant Manage Messages permission to Structra in the channel settings
  2. 2Re-set the sticky with /sticky set

/ad-panel — Delete + Warn: Message Not Found

Advertising

Why it happens

The message link is invalid, or the message was already deleted before the action was run.

How to fix it

  1. 1Paste the full Discord message link (right-click a message → Copy Message Link)
  2. 2If the message was already deleted, warn the user directly with /ad warn instead

/ad-panel — Missing Manage Messages

Advertising

Why it happens

Structra needs Manage Messages permission in the ad channel to delete messages.

How to fix it

  1. 1Go to the ad channel settings → Permissions
  2. 2Grant Manage Messages to Structra

/warn Says You Don't Have Permission

Moderation

Why it happens

Moderation commands require a configured moderator role or the Manage Messages permission.

How to fix it

  1. 1Run /config and navigate to Moderation
  2. 2Set the moderator role, or ask the server owner to add you to it

/purge Stopped Before Finishing

Moderation

Why it happens

This is normal for large purges due to Discord rate limits. The command processes messages in batches.

How to fix it

  1. 1Let it finish — large purges take longer. Run /purge again if messages remain.

/ban Says It Cannot Ban This User

Moderation

Why it happens

You cannot ban users with a role equal to or higher than yours or Structra's role.

How to fix it

  1. 1Check the target user's highest role in Server Settings → Roles
  2. 2Move Structra's role (and yours) above the target's highest role if the ban is appropriate

Security System Is Not Detecting Links

Security

Why it happens

The channel is not in the monitored channels list, or the bot is missing channel permissions.

How to fix it

  1. 1Run /config → Security and confirm the channel is in the monitored channels list
  2. 2Check the bot has Read Message History and Manage Messages in that channel

Staff Are Getting Flagged

Security

Why it happens

Your staff role is not set as an exempt role, so staff messages are checked like everyone else's.

How to fix it

  1. 1Add your staff role as an exempt role in /config → Security

Welcome Message Not Sending

/config

Why it happens

Welcome Messages module not configured in /config, or Structra lacks Send Messages permission in the welcome channel.

How to fix it

  1. 1Run /config → Welcome Messages and ensure the channel is assigned
  2. 2Check that Structra has Send Messages and Embed Links permission in the welcome channel

Join Security Not Triggering

/config

Why it happens

Join Security module is not enabled in /config.

How to fix it

  1. 1Run /config → Join Security and enable the module, then configure the alert channel

Server Logs Missing Events

/config

Why it happens

Log channel not set, or specific log types are not enabled in /config.

How to fix it

  1. 1Run /config → Server Logs
  2. 2Assign a log channel
  3. 3Toggle on the specific event types you want logged

Message content logging requires the Message Content Privileged Intent to be enabled for the bot in the Discord Developer Portal.

Invite Tracking Not Working

/stats

Why it happens

The bot was added after invites were already created, so the invite cache is incomplete.

How to fix it

  1. 1Restart the bot — re-seeds the invite cache on the ready event
  2. 2New invites created after the bot joined will track correctly without a restart

Join the Structra Discord

Ask in the support channel or open a ticket. Include the error message, which command you used, and what you expected vs what happened.

discord.gg/5H3QMzug9t →

Open a Support Ticket

When opening a ticket, include: a screenshot of the error, the full command you used, your server ID, and what you were trying to do.

View full Help docs →
Back to homeFull Help docs →