How to Set Up a Discord Whitelist for Your FiveM Server (2026 Guide)
·by (Founder & Lead Editor)··6 min read·
Gate access to your FiveM server with a Discord role-based whitelist. Covers three implementation approaches (pure Discord, identifier-based, hybrid), step-by-step bot setup, working QBCore and ESX examples, common mistakes that break auth, and security hardening.
Share
How to Set Up a Discord Whitelist for Your FiveM Server (2026 Guide)
A Discord whitelist gates access to your FiveM server using Discord roles. Players without the right role can't join, moderators can grant or revoke access from their phone via a role toggle, and every grant is logged in Discord's audit trail.
This guide covers three implementation approaches, step-by-step bot setup, working configurations for both QBCore and ESX, common mistakes that silently break auth, and security hardening for production servers.
Note on versions: The open-source FAXES/DiscordWhitelist repo is community-maintained and last updated in 2022. It still works for most servers. Several commercial forks exist with active maintenance and SLA support. This guide covers the free GitHub version and the patterns apply to any Discord-based whitelist.
TL;DR
Create a Discord Bot in the Developer Portal → enable Server Members Intent → invite to your guild.
Test: join without the role (blocked), grant the role, rejoin (allowed).
Three Whitelist Approaches: Which One Fits Your Server?
Before picking an implementation, decide which of these three approaches matches your operational reality:
Frequently Asked Questions
Why use Discord for whitelisting a FiveM server?
Discord whitelisting is dynamic (grant access by adding a role, no ACE or DB edits), scalable (moderators can manage access from mobile Discord), and auditable (Discord role history + audit logs show who granted what). The main trade-off vs identifier-based whitelisting is that players must have the Discord desktop app running when connecting, which makes Discord the hard dependency for joining your server.
Turn framework research into a launch-ready script stack
Use this guide to narrow the framework decision, then move into the core commercial hubs for verified scripts, curated bundles, and a faster server launch path.
QBCore starter
Use a complete QBCore base when the guide points to a new server launch and you want jobs, economy, UI, and admin tooling already connected.
View QBCore template
ESX starter
Compare a full ESX server pack when you need a faster path from setup research to a working roleplay stack.
View ESX server pack
Complete server path
If the article is part of a launch plan, start with full server packs that reduce setup time and connect multiple systems faster.
Open full server packs
Premium Scripts You Might Like
Free Scripts You Might Like
Related Articles
Learn how to optimize FiveM server loading times by managing resources, using efficient mods, and choosing the right server host to eliminate annoying delays.
Want to boost your FiveM server population? Let's get you there! So, you've got your FiveM server up and running, that's awesome! But now you're wondering...
Running txAdmin without Discord integration means your community has no way to see server status, scheduled restarts, or player counts without launching the game.
Which whitelist approach should I pick: pure Discord, identifier-based, or hybrid?
Pure Discord role check is simplest and best for servers under 500 concurrent players — one Discord role controls everything. Identifier-based (SQL table of allowed Steam/license IDs) is most secure and independent of Discord, at the cost of manual list management. Hybrid combines both: Discord role for most players, identifier whitelist as break-glass for VIPs/admins when Discord API is down. Hybrid is the right answer for serious servers.
What do I need to set up a Discord whitelist?
Four things: (1) a Discord server where you're admin, (2) a FiveM server with txAdmin or CLI access, (3) players running the Discord desktop app before launching FiveM (so FiveM exposes the discord: identifier), and (4) a bot created in the Discord Developer Portal with the Server Members Intent enabled.
How do I fix the 'Bot offline' error?
Three causes: wrong bot token in config, bot not actually invited to the guild, or the Server Members Intent wasn't enabled in the Developer Portal. Verify the token starts with the correct prefix, check that the bot appears in your Discord member list (offline is fine, not-present is not), and confirm both Intents in the Bot tab of the Developer Portal: Server Members Intent ON, Presence Intent can stay OFF.
Players are blocked even when they have the whitelist role. What's wrong?
The most common cause is the Discord desktop app not running when the player launches FiveM — without it, FiveM can't expose a discord: identifier to the script. Have the player restart Discord, wait for it to fully load, then launch FiveM. If that doesn't fix it, the bot's guild-members cache is stale — reduce cacheMaxTime in the config from 90s to 30s.
Can I use multiple whitelist roles (Donator, Staff, Applied)?
Yes. Add every role ID to the whitelistRoles array in the config. Access is granted if the player has any one of the listed roles. This is how most servers handle funnel differentiation — one role for approved applicants, another for donators, a third for staff with automatic access.
How do I prevent race conditions where role changes take minutes to apply?
Two things: lower cacheMaxTime to 30-60 seconds so the bot refreshes role data more often, and if you need instant updates, implement a webhook on the Discord role-change event that invalidates the cache immediately. Without the webhook, players who just received a role will be denied until the next cache refresh — annoying but usually not worth the implementation effort unless you have high applicant churn.
Is Discord whitelisting secure against bypass attempts?
The weak link is the bot token. If it leaks, attackers can impersonate the bot, read your guild member list, and potentially inject themselves into the whitelist. Store the token outside version control (env var or convar), rotate if leaked, and restrict who has write access to the resource folder. For high-value servers, pair Discord whitelisting with an identifier-based fallback — that way even a complete Discord compromise doesn't grant server access.
Deep Dive: How to Set Up a Discord Whitelist for Your FiveM Server (2026 Guide)
Understanding How to Set Up a Discord Whitelist for Your FiveM Server (2026 Guide) is essential for anyone running a FiveM server in 2026. The ecosystem has moved toward modular frameworks, heavier asset streaming, and higher player expectations for stability. Whether you are troubleshooting a specific error or planning a new feature, the principles below will save time and prevent common mistakes.
Start with the fundamentals
Before changing any configuration, confirm your server artifact version, framework build, and resource load order. Most mysterious failures trace back to one of these three basics. Keep a staging environment that mirrors production so you can test changes without risking your live player base.
Document your environment
Every successful server owner maintains a simple runbook that lists started resources, installed versions, custom configuration changes, and known issues. When something breaks at night, that runbook is worth more than any troubleshooting script.
Measure before optimizing
Use resmon, server console logs, and database query logs to establish a baseline. Guessing about performance usually leads to removing the wrong resources or over-allocating hardware. Data-driven decisions keep your server healthy as it grows.
Security and permissions
Limit admin access to the minimum required. Use ACE principals or database groups correctly, rotate credentials after staff changes, and never run resources from untrusted sources without scanning them first. A single backdoored resource can undo months of community building.
Related FiveMX resources
For scripts, vehicles, MLO interiors, and complete server packs, visit the FiveMX marketplace. Our free FiveM mods library includes hundreds of tested resources, and our FiveM scripts category covers everything from economy to police systems.
These related guides go deeper on adjacent topics:
Back up before any change, test on a staging server first, monitor logs for errors after each update, keep your resource list clean and documented, and ask for help in trusted community channels when stuck. Following these habits will make this topic a manageable part of your server rather than a recurring crisis.
