streamlinx
docs

Troubleshooting

Common issues and their solutions. If you can't find your issue here, join our Discord support server.

Bot Issues

Bot Not Responding to Commands

Symptoms: Commands show error or no response

Possible Causes:

  1. Bot is offline or restarting
  2. Missing permissions
  3. Discord is experiencing issues

Solutions:

  1. Verify bot has these permissions:
    • Send Messages
    • Embed Links
    • Use Slash Commands
  2. Try again in a few minutes (Discord may be slow)
  3. Re-invite bot with correct permissions

Try running /help to check if bot is responding. If no response, bot may be offline or missing permissions.

"Missing Permissions" Error

Error Message: "You need Manage Server permission to use this command"

Solution:

  1. Verify you have "Manage Server" role in Discord
  2. Server Settings → Roles → Your Role → Enable "Manage Server"
  3. If you're the server owner, you automatically have this permission

Commands Not Appearing

Symptoms: Slash commands don't show in autocomplete

Possible Causes:

  1. Bot recently added (commands take 1 hour to sync)
  2. Discord cache issue
  3. Bot missing permissions

Solutions:

  1. Wait up to 1 hour for commands to sync
  2. Restart Discord client (Ctrl+R or Cmd+R)
  3. Re-invite bot using the invite link
  4. Check bot has "Use Application Commands" permission

Bot Left Server Unexpectedly

Possible Causes:

  1. Someone kicked the bot
  2. Bot was banned
  3. Service maintenance

Solutions:

  1. Check Audit Log (Server Settings → Audit Log)
  2. Re-invite bot using the invite link
  3. Check #announcements in support Discord for maintenance notices

Notification Issues

Not Receiving Notifications

Symptoms: Streamer is live but no notification sent

Check These First:

  1. Verify Streamer is Tracked:

    • Use /portal to open the web dashboard
    • Confirm streamer appears in your streamers list

  2. Check Notification Channel:

    • Bot needs "Send Messages" permission in channel
    • Channel not deleted or archived
    • Check in the Web Portal which channel is assigned

  3. Verify Streamer is Actually Live:

    • Check on platform (Twitch/YouTube/Kick)
    • May be marked as live but in waiting room (YouTube)

  4. Check Bot Online Status:

    • Bot must be online to send notifications
    • Check bot status in member list

Advanced Troubleshooting:

Platform Connection Issues

Monitoring may fail to start if: - Platform is experiencing issues - Bot restarted recently (reconnecting) - Streamer account is banned/suspended

Solution:

  1. Remove streamer: /streamer remove platform:Twitch username:username
  2. Wait 30 seconds
  3. Re-add streamer: /streamer add platform:Twitch username:username channel:#channel
  4. This resets the monitoring connection

Duplicate Notifications

Symptoms: Multiple notifications for same stream

Possible Causes:

  1. Streamer added multiple times
  2. Multiple notification channels configured
  3. Bot error (rare)

Solutions:

  1. Use /portal to open the Web Portal - check for duplicate entries
  2. Verify expected notification channels in the dashboard
  3. Remove duplicate entries
  4. If issue persists, contact support

Delayed Notifications

Symptoms: Notifications arrive 5+ minutes after stream starts

Expected Delays by Platform:

  • Twitch: Under 30 seconds
  • YouTube: 2-5 minutes (platform limitation)
  • Kick: Under 30 seconds

If Delays Are Longer:

  1. Check Platform Status:

  2. Connection Refresh:

    • Platform connections occasionally need renewal
    • Bot automatically handles this, but issues can occur
    • Solution: Remove and re-add streamer

  3. Discord Issues:

If consistent delays only affect certain streamers, their platform data may be cached. This is a platform issue, not Streamlinx.

Notifications Missing Information

Symptoms: Embed shows "Unknown Game" or missing thumbnail

Causes:

  1. Platform didn't provide data
  2. Streamer hasn't set game/category
  3. New game not in platform database

Solutions:

  • Usually resolves automatically when streamer updates info
  • Not a bot error if streamer hasn't set category
  • Check streamer's actual stream page to confirm

Wrong Notification Channel

Symptoms: Notifications going to wrong channel

Solution:

  1. Use /portal to see current channel assignments in the Web Portal
  2. To change channel:
    • Remove streamer: /streamer remove platform:Twitch username:username
    • Re-add with correct channel: /streamer add platform:Twitch username:username channel:#correct
    • Or edit the streamer in the Web Portal to change the channel

Notification channel deleted

A notification channel was deleted in Discord. Streamlinx has paused the affected streamers and live role configs until a replacement channel is set - nothing was permanently removed.

Fix:

  1. Create a new channel, or pick an existing one.
  2. Open the portal and set the new notification channel for each affected streamer or live role.
  3. Streamers and live roles resume automatically once the channel is set.

Bot can't post

If your streamer notifications are landing in the wrong channel (or not appearing at all), the most common cause is that the Streamlinx bot doesn't have permission to post in your configured channel.

How Streamlinx detects this

Starting from v0.7.0, Streamlinx validates channel permissions at three points:

  • When you pick a channel in the portal: the dropdown dims channels the bot can't post to, and selecting one shows an inline alert with fix steps.
  • When the bot tries to send a notification: after three consecutive failures on the same channel, we flag the streamer in the portal and send a single DM to the server owner summarizing the issue.
  • On a periodic background sweep: every 30 minutes, we re-check channel permissions so problems surface before your next broadcast.

Fixing channel permissions

If you've received a DM or seen a "channel permission issue" flag in the portal:

  1. In Discord, right-click the affected channel → Edit Channel → Permissions.
  2. Add the Streamlinx role if it's not already listed.
  3. Enable these three permissions for the Streamlinx role:
    • View Channel
    • Send Messages
    • Embed Links
  4. Save the channel.
  5. Back in the Streamlinx portal, click Re-check permissions on the alert banner. The status should update immediately.

If the problem persists, check whether a category-level permission overwrite is blocking access. Channel-level permissions can be overridden by the parent category, so you may need to grant the Streamlinx role access on the category as well.

Managing notification DMs

If you'd rather not receive these DMs, you can turn them off in Portal → Settings → Owner Alerts. The four toggles are:

  • Streamer unavailable alerts: streamers that become unavailable on their platform
  • Channel permission alerts: channels where the bot can't post
  • Live role permission alerts: live roles the bot can't manage
  • Webhook deactivation alerts: custom webhooks that have been auto-deactivated after three failures

Problems will still be flagged in the portal even if you disable DMs. For a full walkthrough of the toggles, see Server Settings: Owner Alerts in the Web Portal guide.

Custom webhooks deactivated

If you've received a "Custom webhooks deactivated" owner-alert DM, one or more custom webhook URLs configured for your streamers (or for the guild default) failed three consecutive delivery attempts and Streamlinx automatically disabled them.

Notifications for those streamers are paused. Affected streams won't produce a Discord notification until you either repair the webhook or clear it from the affected streamer's settings (which lets the bot take over delivery again).

Common causes

  1. Webhook deleted in Discord: the webhook URL still exists in the portal, but the destination was removed from the server's integrations list.
  2. Destination channel deleted, archived, or made private: the channel the webhook posts to is no longer reachable by the webhook's stored permissions.
  3. Webhook URL rotated: someone regenerated the webhook in Discord, invalidating the old URL stored in the portal.

How to fix: option A - repair the webhook

  1. Open Server Settings → Integrations → Webhooks in Discord and confirm the webhook still exists. If it was deleted, recreate it (or pick a different one).
  2. Confirm the webhook's destination channel is accessible to it.
  3. Back in the Streamlinx portal, open the affected streamer (or the guild settings if the webhook is the guild default), paste the current webhook URL into the field, and let the inline verifier confirm it resolves to a real channel.
  4. Save. The "deactivated" badge clears automatically once delivery succeeds; notifications resume via the custom webhook identity.

How to fix: option B - drop the custom webhook

If you no longer want a custom-identity webhook for the streamer, clear the webhook URL field in the portal and save. Streamlinx will resume sending notifications via the default Streamlinx bot account.

If you'd like to suppress the DM for these events, see Managing notification DMs above. The portal still flags affected streamers regardless.

Custom webhook deleted

A custom webhook configured for streamer notifications no longer exists in Discord. Streamlinx has paused delivery for the affected streamers - notifications will resume once you update or remove the webhook configuration.

Fix:

Choose one:

  • Recreate the webhook. Create a new webhook in Discord, then update the custom webhook URL in the affected streamer's portal settings.
  • Remove the custom webhook. Delete the custom webhook URL in the streamer's portal settings - notifications will fall back to the default Streamlinx bot account.

Live role permission failing

Streamlinx cannot assign or remove the live role from members who go live on Twitch because the bot's role is positioned below the live role in your server's role hierarchy, or the live role was deleted.

Fix:

  1. Open Server Settings → Roles in Discord.
  2. Drag the Streamlinx role above the affected live role.
  3. For a deleted live role, open the live role configuration and either pick a different role or remove the config.

Streamlinx will resume assignments automatically once permissions are fixed.

Live role deactivated (role deleted)

The live role (or its filter role) was deleted in Discord. Streamlinx has deactivated the corresponding live role config to avoid assigning a role that no longer exists, or assigning a role unrestricted when the filter role that restricted it is gone.

Fix:

  1. Create a new role in Server Settings → Roles in Discord.
  2. Open your live role configuration and pick the new role (or filter role).
  3. Reactivate the live role config.

Quiet hours role removed

Your quiet hours mention role was deleted in Discord. Streamlinx still posts the quiet hours summary, but no role will be pinged until you pick a replacement mention role.

Fix:

  1. Create a new role in Server Settings → Roles in Discord, or select an existing role.
  2. Open your portal server settings and set the new quiet hours mention role.

Template mentions invalid

Some notification templates reference roles or channels that were deleted from your server. Notifications still send, but the deleted mentions render as @unknown-role or #deleted-channel instead of working links.

Fix:

  1. Open the affected streamer or live role in the portal.
  2. Edit the template fields to remove or replace the dead mentions.
  3. Save - Streamlinx validates mentions at save time so you'll see inline warnings if any remain.

Web Portal Issues

Can't Login

Symptoms: OAuth redirect fails or shows error

Possible Causes:

  1. Discord OAuth app misconfigured
  2. Popup blocked by browser
  3. Session cookies disabled

Solutions:

  1. Allow popups from streamlinx.io
  2. Enable cookies in browser settings
  3. Try different browser
  4. Clear browser cache and cookies
  5. Disable ad blockers temporarily

Server Not Showing in List

Symptoms: Your Discord server missing from portal

Requirements:

  • You must have "Manage Server" permission
  • Bot must be in the server
  • Server must have at least setup completed

Solutions:

  1. Verify "Manage Server" permission in Discord
  2. Ensure bot is invited to server
  3. Logout and login again to refresh
  4. Use /streamer add in Discord to track your first streamer

Changes Not Saving

Symptoms: Settings revert after saving

Possible Causes:

  1. Network error
  2. Session expired
  3. Validation error

Solutions:

  1. Check browser console for errors (F12)
  2. Verify network connection
  3. Logout and login again
  4. Try different browser

Dashboard Shows Old Data

Symptoms: Live status not updating

Solution:

  • Dashboard auto-refreshes every 30 seconds
  • Manually refresh browser page (F5)
  • Clear browser cache

Streamer Issues

"Invalid Username" Error

Error: Cannot add streamer - invalid username

Correct Username Formats:

Twitch:

  • ✅ ninja (just the username)
  • ✅ pokimane
  • ❌ https://twitch.tv/ninja (use just the username, not full URL)

YouTube:

  • ✅ @MrBeast (channel handle with @)
  • ✅ mrbeast (handle without @)
  • ❌ https://youtube.com/@MrBeast (use just the handle, not full URL)

Solution: Use just the username/handle from the streamer's channel page

"Streamer Already Tracked" Error

Error: Cannot add - streamer already tracked

Solutions:

  1. Use /portal to view your streamers list and find the existing entry
  2. If you want it in different channel:
    • Remove existing: /streamer remove platform:Twitch username:username
    • Re-add with new channel: /streamer add platform:Twitch username:username channel:#new-channel
  3. If you don't see it in list but get error:
    • May be tracked in different server you manage
    • Streamers can only be tracked once per server

Streamer unreachable

Error: Platform cannot find streamer (also surfaces as a "Streamers unreachable" owner-alert DM after 24h)

Possible Causes:

  1. Username Changed: Streamer changed their username
  2. Account Deleted: Account no longer exists
  3. Account Suspended: Temporarily banned by platform
  4. Typo: Wrong username in URL

Solutions:

  1. Verify the streamer's current handle on their platform page (Twitch / YouTube / Kick).
  2. If they renamed, remove the old entry from the portal and re-add with the new username.
  3. If the account was deleted or banned, remove the entry from the portal entirely.
  4. If you suspect a transient platform issue, try again in a few minutes.

Can't Remove Streamer

Error: Removal fails or streamer reappears

Solutions:

  1. Verify streamer name spelling (use autocomplete)
  2. Check you have "Manage Server" permission
  3. Try via web portal instead of Discord command
  4. If issue persists, contact support with streamer ID

Premium & Subscription Issues

Premium Not Activating

Symptoms: Purchased premium but features not unlocked

Solutions:

  1. Wait up to 5 minutes for activation
  2. Run /subscription to check your tier status
  3. Verify purchase in Discord → User Settings → Subscriptions
  4. Contact support with transaction ID

Premium Features Not Working

Symptoms: Custom notification identity or advanced features not available

Check:

  1. /subscription - verify tier shows "Premium"
  2. Check subscription expiration date
  3. Ensure payment method is valid

Solutions:

  1. If expired, renew subscription in Discord settings
  2. Contact support if active but not working

Can't Upgrade to Premium

Symptoms: Upgrade button doesn't work

Solutions:

  1. Verify server is eligible (community server with bot)
  2. Check Discord Nitro required for server subscriptions
  3. Try desktop Discord app instead of web
  4. Clear Discord cache and restart

Template Issues

Template Not Applying

Symptoms: Notifications still use the default embed format instead of your custom template

Solutions:

  1. Verify template saved in the Web Portal (use /portal to access)
  2. Check for invalid variables (must use exact names)
  3. Ensure correct platform selected (Twitch/YouTube/Kick)
  4. Template applies to new notifications only (not retroactive)

Template Variables Not Working

Symptoms: Variables like {streamer} showing as literal text

Common Mistakes:

  • Wrong brackets: [streamer] ❌ Should be {streamer} ✅
  • Extra spaces: { streamer } ❌ Should be {streamer} ✅
  • Wrong case: {STREAMER} ❌ Should be {streamer} ✅
  • Typos: {stremer} ❌ Should be {streamer} ✅

Valid Variables:

Common (all notifications):

  • {streamer} - Streamer display name
  • {username} - Platform username/handle
  • {platform} - Platform name (Twitch, YouTube, Kick)
  • {title} - Stream title
  • {game} - Game/category
  • {url} - Direct link to stream

Live notifications only:

  • {viewer_count} - Current viewer count

Offline notifications only:

  • {duration} - How long stream lasted
  • {vod_url} - Link to VOD/recording

Template Too Long

Error: Template exceeds character limit

Limits:

  • Message: 2000 characters
  • Embed title: 256 characters
  • Embed description: 4096 characters

Solution:

  1. Shorten template text
  2. Remove unnecessary variables
  3. Use shorter custom text

Performance Issues

Bot Responding Slowly

Possible Causes:

  1. High server load
  2. Discord rate limits
  3. Large server with many commands

Solutions:

  • Usually resolves within a few minutes
  • If persistent, contact support

Web Portal Loading Slowly

Solutions:

  1. Clear browser cache
  2. Disable browser extensions
  3. Check network connection
  4. Try incognito mode
  5. Use different browser

Common Error Messages

"Rate Limited"

Meaning: Too many requests in short time

Solution: Wait 30 seconds and try again

"Bot Missing Permissions"

Meaning: Bot cannot perform action in channel

Required Permissions:

  • Send Messages
  • Embed Links
  • Manage Webhooks (for custom name/avatar)
  • Read Message History

Solution:

  1. Server Settings → Roles → @Streamlinx
  2. Enable missing permissions
  3. Or give permissions in channel settings

"Internal Server Error"

Meaning: Unexpected error on our side

Solution:

  1. Try again in a few minutes
  2. If persists, contact support with:
    • Timestamp of error
    • Command used
    • Server ID

Getting Help

If your issue isn't listed here:

  1. Search Documentation:

  2. Check Status Page:

  3. Join Support Server:

  4. Contact Support:

When Reporting Issues, Include:

  • What you were trying to do
  • What command/page you used
  • Expected vs actual behavior
  • Screenshots (if applicable)
  • Server ID and streamer name (if relevant)
  • Error messages (exact text)
Quick Response Tips

Provide as much detail as possible in your first message. This helps us resolve your issue faster without back-and-forth questions.