Skip to main content

Troubleshooting & FAQ

Use this page when something does not work as expected. Most issues are permission, premium tier, or configuration related.

Quick diagnostics​

flowchart TD
    A[Something broke] --> B{Dashboard Error Logs?}
    B -->|Yes| C[Read error + retry]
    B -->|No| D{Recent config change?}
    D -->|Yes| E[Check Audit Log / revert]
    D -->|No| F{Bot online?}
    F -->|No| G[Check Discord status / re-invite]
    F -->|Yes| H[Permissions & channel rules]

Dashboard → Diagnostics → Troubleshoot can copy a support bundle and queue server re-initialization.

Bot & permissions​

Bot is offline​

Missing permissions​

  • Compare against Required Bot Permissions
  • Ensure bot role is above roles it must assign or mention
  • For Auto Setup: Manage Channels, Manage Webhooks, Manage Threads

Cannot see server in dashboard​

  • You need Administrator or delegate access
  • Refresh guild list on dashboard home
  • Sign out and back in

Translation issues​

Translations use low quality / wrong engine​

  • Free servers use self-hosted engine by default
  • Start a trial or upgrade for managed Groq
  • BYOK users: verify key and model in User or Server settings
  • Check engine resolution in BYOK overview

Context menu says premium required​

  • In DMs or servers without guild install, user premium is required
  • User-install the app and subscribe, or ask an admin to install the bot in the server

Flag reactions do nothing​

  • Channel may be ignored — /ignore or Ignored Channels
  • Unsupported flag emoji
  • Feature disabled in customization

/translate command not found​

  • Most commands are disabled by default — enable in Dashboard → Commands → Deploy

Mirroring & Auto Setup​

Messages not bridging (Channel Mirroring)​

  • Channels must be in the same mirror group with languages assigned
  • Bot needs Manage Webhooks in each channel
  • Run Conversations → Scan/Fix in dashboard for stale groups

Auto Setup channels missing​

  • Click Repair on the mirror in Auto-Setup
  • Check queue status in mirror manager
  • Verify premium tier or trial has not expired

Threads not syncing​

  • Enable threads feature flag in customization
  • Bot needs Manage Threads, Send Messages in Threads
  • Forum channels need Create Public Threads
  • v3.15.0+ includes thread mirroring fixes — ensure bot is up to date

Wrong channel mapping after renames​

  • Run mirror Scan then Repair
  • Avoid manual channel moves during active queue jobs

BYOK & API errors​

Error patternFix
401 / invalid keyRegenerate key at Groq/OpenAI; re-save in dashboard
Model not foundUse current model ID from provider docs
Rate limitedReduce volume or upgrade provider tier
Broken mentions/linksAdjust protection delimiters
High costsLower max tokens; use managed Groq for bulk server traffic

Performance & delays​

Under very heavy load, translations and mirrors may queue briefly. This is normal.

  • Premium tiers use a faster translation queue
  • Internal write-gate rate limits Discord API calls to avoid global 429s — mirrors may lag seconds, not minutes, during spikes
  • Check Error Logs for sustained failures vs normal queueing
Operator note

Queue intervals and write-gate tuning are platform-level settings, not exposed in the server dashboard. Contact support if delays persist for hours.

Billing & premium​

Trial already used​

Subscription not applying​

  • Allow a few minutes after Stripe checkout
  • Open server overview — tier badge should update
  • Use Refresh on dashboard home

Move subscription to another server​

Dashboard → Overview → Subscription Management → Move subscription (admin only)

Premium ended​

  • Configurations are saved but premium features (Auto Setup, managed engine) pause
  • Re-subscribe to resume without reconfiguring

Commands & branding​

Custom command names not showing​

  • Click Deploy Commands after edits
  • Bot language change triggers redeploy — wait for progress modal to finish
  • Context menu names allow spaces; slash names must be lowercase a-z0-9_-

Staff cannot run admin commands​

  • Check role restrictions on Commands page
  • Administrators and server owner bypass restrictions

FAQ​

What is the difference between Channel Mirroring and Auto Setup?​

Feature Terminology — Channel Mirroring links existing channels; Auto Setup clones whole categories (premium).

Do I need premium for mirroring?​

Basic Channel Mirroring is free. Auto Setup requires Server Boost or trial.

Can I use my own OpenAI key?​

Yes — User or Server BYOK – OpenAI tiers. See BYOK.

Does Translate show translations to everyone?​

The Translate context menu is ephemeral (only you). Flag reactions are public unless configured otherwise.

How do I get free premium?​

Vote on top.gg for 12 hours of user premium. Details

Are AI profiles available?​

Yes — on the beta dashboard. Create profiles under User Settings or Server Configuration, then assign them to mirrors, default-language channels, flag reactions, and the Translate context menu. See AI profiles. Production rollout may lag beta.

Can I document my setup for staff?​

Yes — share this docs site and your delegate list.

Still stuck?​

  1. Copy the troubleshoot bundle (Dashboard → Troubleshoot)
  2. Check hbtranslate.com/support knowledge base
  3. Join the Discord support server
  4. Premium servers: open a support ticket from the dashboard