Troubleshooting

Solutions to the most common problems when setting up or running the RoPerms SDK.

SDK not connecting (Ping returns false)#

• HTTP requests disabled — go to File → Game Settings → Security and enable Allow HTTP Requests. The setting only takes effect after publishing the place.
• Wrong API key — copy the key fresh from Settings → API. Ensure there are no extra spaces or newlines.
• Place not claimed — the API key check also validates that the requesting Place ID is registered under your org. Go to Settings → Places and add the place ID.
• Wrong base URL — double-check the baseUrl in CONFIG matches your deployment (e.g., https://roperms.app).
• Studio-only — Studio does not always use the published Place ID. Test in a published game rather than Studio play mode if Ping keeps failing.

Modcall command not working#

TextChatService vs legacy chat

Roblox's default chat since 2023 is TextChatService. Player.Chatted does not fire under it — only TextChatCommand does. EnableModcallCommand() registers both automatically. If your game explicitly uses the legacy chat (set in TextChatService to ChatVersion.LegacyChatService), both paths are still wired up.

If modcalls are not arriving in the dashboard after typing the command, check:

• That EnableModcallCommand() is called before any players join.
• That the player is not modcall-banned (check their profile).
• That the SDK is connected (Ping returns true).

Bans not enforcing on join#

• Enforcement not enabled — make sure you call RoPerms.EnableEnforcement() in your server script.
• Init not called — RoPerms.Init() must be called beforeEnableEnforcement(). Both should be at the top of the script, before any PlayerAdded connections fire.
• Cache is stale — a ban issued immediately before a player joins may be in the cache from a previous session. The cache TTL is cacheDuration seconds (default 60). For critical bans, call RoPerms.Invalidate(player) immediately after banning.

Tool bans / chat bans not applying#

• Client script not installed — RoPermsClient.lua must be placed as a LocalScript inside StarterPlayer → StarterPlayerScripts. The server cannot hide CoreGUI elements — only client scripts can.
• Client script not reaching server — verify the LocalScript is running by adding a print("RoPermsClient loaded") at the top and checking the developer console in a live server.
• Cache lag — the client fetches status from the server module on join. If the ban was applied just before the player joined, the cache might not reflect it yet. Call Invalidate server-side then wait for the client to refresh.

Payments not working#

• PRODUCTS table mismatch — the Robux amount on the payment link must exactly match a key in the PRODUCTS table in RoPermsPayments.lua. Check both the link amount and the table keys.
• Conflicting ProcessReceipt — only one script can set MarketplaceService.ProcessReceipt. Remove any other handler you have and let RoPermsPayments.lua own it exclusively.
• Developer Product not published — the Developer Product must be publicly available (not draft) for players to purchase it. Check the Creator Dashboard.
• Player not prompted — GetOpenPayments is polled everypollInterval seconds. The customer must be in-game for the poll to fire. If the customer joined before the payment link was created, they should be prompted within pollInterval seconds of link creation.

Ranking failing#

• Cookie expired — Roblox cookies expire. Re-log as the bot account and update the cookie in Settings → Integrations.
• Bot lacks permission— ensure the bot's group role has "Rank Members" checked. The bot cannot promote players to a rank equal to or above its own rank.
• OAuth refresh failure — if using OAuth, reconnect in Settings → Integrations → Ranking. Cookie auth is more reliable for long-running setups.

Audit logs not appearing#

Every mutation in the dashboard writes an audit entry. If entries are missing:

• Verify the action actually succeeded (check for error notifications in the dashboard).
• SDK-initiated actions use sdkAudit()which records a null actor — they appear in the audit log with "SDK" as the actor name.
• Filter by the correct action prefix in the Audit table (e.g., ban.*, session.*).

Getting help#

If you have exhausted the steps above, collect the following information before reaching out for support:

• The exact error message or unexpected behaviour.
• Your Roblox Place ID and org name.
• The SDK version (visible at the top of RoPerms.lua).
• The output console logs from a live server (use the F9 developer console in Roblox).