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

Name contains the word Discord​

Discord rejects a webhook name that impersonates Discord. If your username, nickname, or global name contains the word Discord, mirrored posts for you may fail until that name is adjusted, while everyone else still translates. HephBot rewrites that word to Disc0rd on the webhook name. Your message text stays the same, and channel names are not changed.

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