> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mira.party/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> The problems people actually run into, and what fixes them.

## Commands

<AccordionGroup>
  <Accordion title="The bot doesn't respond at all" icon="ban">
    In order of likelihood:

    1. **Wrong prefix.** `@mira ping` always works — mentioning is a prefix no matter what's configured.
    2. **The channel is ignored.** `!ignore list`
    3. **The command or its category is disabled.** `!command disable list` and `!module disable list`
    4. **mira can't see or speak in the channel.** It needs View Channel, Send Messages and Embed Links. Check the channel's overwrites, not just the role.
    5. **You're ignored.** Also `!ignore list`.
  </Accordion>

  <Accordion title="It says I don't have permission" icon="lock">
    Check what the command needs:

    ```javascript theme={null}
    !help ban
    ```

    If you should have it, a channel-level deny is probably overriding your role. If you *shouldn't* have it but need it, [fake permissions](/security/fake-permissions) grant bot-only access without the real Discord permission.
  </Accordion>

  <Accordion title="It works on some people but not others" icon="layer-group">
    Role hierarchy. Discord won't let anyone manage a member whose highest role is at or above their own — this applies to mira and to you.

    **Fix:** drag mira's role near the top of your role list, above your staff roles.

    The server owner can never be punished by anyone.
  </Accordion>

  <Accordion title="I changed the prefix and can't remember it" icon="terminal">
    ```javascript theme={null}
    @mira prefix
    ```

    Mentioning the bot always works.
  </Accordion>

  <Accordion title="Another bot uses the same prefix" icon="robot">
    Change yours, or set a [personal prefix](/getting-started/prefixes#your-own-personal-prefix) that only affects you:

    ```javascript theme={null}
    !prefix set ;
    !prefix self ;
    ```
  </Accordion>
</AccordionGroup>

## Roles

<AccordionGroup>
  <Accordion title="Reaction/button roles aren't working" icon="hand-pointer">
    * mira's role must be **above** the role being given
    * It needs **Manage Roles**
    * For reaction roles specifically, it needs **Add Reactions** and **Read Message History**

    If people have a reaction but no role, Discord dropped the event:

    ```javascript theme={null}
    !reactionrole sync <message>
    ```

    If a message lost its buttons after being edited:

    ```javascript theme={null}
    !buttonrole render <message>
    !dropdownrole render <message>
    ```
  </Accordion>

  <Accordion title="Autoroles aren't applying" icon="user-plus">
    If your server has membership screening ("Complete the rules screening"), members are **pending** until they accept. Autoroles apply after they accept, not on the initial join. This is correct behaviour but catches people out when testing.
  </Accordion>

  <Accordion title="Booster roles aren't being created" icon="gem">
    * The member has to actually be boosting, or hold a role added via `!boosterrole include`
    * mira needs **Manage Roles**
    * Set a base position so they don't scatter: `!boosterrole base @Booster`
    * Discord caps a server at 250 roles
  </Accordion>

  <Accordion title="Muted people can still talk in some channels" icon="volume-high">
    The mute role's overwrites weren't applied to channels created after setup:

    ```javascript theme={null}
    !mute sync
    !jail sync
    ```
  </Accordion>
</AccordionGroup>

## Scripts

<AccordionGroup>
  <Accordion title="My embed sends as plain text" icon="code">
    A script with no recognised node names is treated as plain content. Check for typos — `{tilte:}` won't be recognised, so the whole thing falls back to text.

    Test with `!embed <script>` before committing it to a config.
  </Accordion>

  <Accordion title="Invalid Form Body when using buttons or sections" icon="triangle-exclamation">
    Button and section parts are separated by **whitespace**, not `&` or `&&`:

    ```javascript Wrong theme={null}
    {button: label: "Rules" & style: secondary}
    ```

    ```javascript Right theme={null}
    {button: label: "Rules" style: "secondary"}
    ```

    An `&` gets absorbed into the preceding value, so the key before it is lost entirely — which Discord reports as a missing `label` or a section with 0 components.

    `&&` is only for multi-part **embed** nodes: `{author:}`, `{footer:}`, `{field:}`.
  </Accordion>

  <Accordion title="A variable shows as literal text" icon="brackets-curly">
    That variable isn't available in that context. A welcome message knows about `{user}`; a counter channel uses a completely [different, flatter set](/setup/counters#variables).

    Most modules have a `variables` subcommand listing what they support:

    ```javascript theme={null}
    !welcome variables
    !counter variables
    !invoke variables
    ```
  </Accordion>

  <Accordion title="Mentions in my embed don't ping" icon="at">
    Discord only sends notifications from message **content**, not embeds. Put the mention in `{content:}`:

    ```javascript theme={null}
    {content: {user.mention}} {title: Welcome!}
    ```
  </Accordion>

  <Accordion title="The message doesn't send at all" icon="square-xmark">
    You're probably over a Discord limit: 40 components, 10 buttons across 5 rows, or 4000 characters of text. Trim it down.
  </Accordion>
</AccordionGroup>

## Feeds and reposting

<AccordionGroup>
  <Accordion title="A social feed stopped posting" icon="rss">
    * The account may have gone private — feeds stop silently
    * The account may have been renamed
    * Check it's still configured: `!tiktok list`
    * mira needs Send Messages and Embed Links in the target channel

    Feeds **poll**, so there's always a delay of a minute or more.
  </Accordion>

  <Accordion title="Reposting isn't working" icon="link">
    ```javascript theme={null}
    !reposter status on
    !reposter disable list
    !reposter platforms
    ```

    Also check whether reposting is [restricted to roles](/social/reposter#behaviour) you don't have. Private, deleted, age-restricted and geo-blocked content can't be fetched.
  </Accordion>

  <Accordion title="Videos are missing from reposts" icon="video">
    Discord's upload limit — mira will automatically host the content on our own server to bypass Discord's limit.
  </Accordion>
</AccordionGroup>

## Music and voice

<AccordionGroup>
  <Accordion title="The bot joins but plays nothing" icon="volume-xmark">
    It needs **Speak** in the voice channel, not just Connect. Check the channel's overwrites.
  </Accordion>

  <Accordion title="Spotify commands do nothing" icon="spotify">
    [Spotify remote control](/audio/spotify) needs an **active device** — play something in the Spotify app first, then `!spotify device` to confirm the target. Playback control also requires Premium; that's Spotify's restriction.
  </Accordion>

  <Accordion title="VoiceMaster channels aren't being created" icon="microphone">
    mira needs **Manage Channels** and **Move Members**, and the category needs room — Discord caps a category at 50 channels. If the join-to-create channel was deleted, re-run `!voicemaster setup`.
  </Accordion>
</AccordionGroup>

## Configuration

<AccordionGroup>
  <Accordion title="Counter channels aren't updating" icon="hashtag">
    Discord rate-limits channel renames to **twice per 10 minutes**, per channel. Counters update roughly every 10 minutes as a result. `!counter refresh #channel` forces one immediately.

    Running many counters spreads that budget thin — three or four is usually plenty.
  </Accordion>

  <Accordion title="Logging is missing messages" icon="scroll">
    A bot can only log what it can see. Messages from before mira joined, or in channels it can't view, aren't recoverable — that's a Discord limitation, not a missing feature.

    Make sure it has **View Channel** and **Read Message History** everywhere.
  </Accordion>

  <Accordion title="Tickets aren't opening" icon="ticket">
    * Re-publish the panel after any option change: `!tickets resend Support`
    * Check the member isn't blocked by [required roles](/setup/tickets/access#required-roles), a blacklist, or the per-panel ticket limit
    * Check the category isn't full — set an overflow category
  </Accordion>

  <Accordion title="I nuked a channel and things broke" icon="explosion">
    `!nuke` gives the channel a **new ID**. Anything referencing the old one breaks: sticky messages, counters, ticket panels, webhooks, pinned links. Re-point them.
  </Accordion>

  <Accordion title="Antinuke banned someone it shouldn't have" icon="shield-halved">
    Whitelist people who legitimately do bulk work, then undo it:

    ```javascript theme={null}
    !antinuke whitelist @headadmin
    !unban 111111
    ```

    The alert message has a **restore** button for deleted roles and channels, valid for **one hour**. After that, [backups](/setup/backups).
  </Accordion>
</AccordionGroup>

## Recovering from an attack

<Steps>
  <Step title="Stop the bleeding">
    ```javascript theme={null}
    !antiraid pause 30m
    !lockdown all
    ```
  </Step>

  <Step title="Remove the attackers">
    ```javascript theme={null}
    !massban 111111 222222 --history 1d
    !purge bots 100
    ```
  </Step>

  <Step title="Undo the damage">
    Use the **restore** button on the antinuke alert if it's within the hour. Otherwise `!backup`.
  </Step>

  <Step title="Reopen">
    ```javascript theme={null}
    !unlockdown all
    !antiraid resolve
    ```
  </Step>

  <Step title="Work out how it happened">
    ```javascript theme={null}
    !history moderator @whoever
    !antinuke settings
    ```

    Then tighten the thresholds and trim the whitelist.
  </Step>
</Steps>

## Still stuck?

* `!help <command>` — exact syntax, permissions and an example
* [mira.party/commands](https://mira.party/commands) — every command, searchable
* [Support server](https://discord.gg/SFBA7WVCvw) — for anything else