Troubleshooting

Troubleshooting Guide

Solve common AkuWorks issues quickly with our comprehensive troubleshooting guide. Find solutions for verification problems, permission errors, and configuration issues.

Need Immediate Help?

If you're experiencing a critical issue that's preventing your server from functioning:

Quick Fixes

Try these quick solutions for common issues before diving into detailed troubleshooting:

Bot appears offline

2 minutes

Check Discord status page and bot permissions

Verification button not working

1 minute

Refresh Discord and try again, check bot permissions

Users not getting verified role

3 minutes

Check role hierarchy and auto-assignment settings

Verification taking too long

2 minutes

Check timeout settings and Cloudflare status

Common Issues

Bot Not Responding

The AkuWorks bot is not responding to commands or verification attempts

high priority

Quick Solutions:

Check if the bot is online in your server member list
Verify the bot has proper permissions
Ensure the bot role is above other roles in hierarchy
Check Discord API status for outages

Verification Failures

Users are unable to complete the verification process

high priority

Quick Solutions:

Check Cloudflare Turnstile configuration
Verify timeout settings are appropriate
Review rate limiting settings
Test verification process yourself

Permission Errors

Bot lacks necessary permissions to function properly

medium priority

Quick Solutions:

Grant required permissions to bot role
Move bot role above managed roles
Check channel-specific permissions
Verify server-wide permissions

Role Assignment Issues

Verified users are not receiving the correct roles

medium priority

Quick Solutions:

Check role hierarchy positioning
Verify auto-role assignment is enabled
Ensure roles exist and are configured
Review role permission settings

Diagnostic Process

Follow this systematic approach to diagnose and resolve issues:

Check Bot Status

Verify the bot is online and has proper permissions

Check member listVerify bot roleTest basic commands

Review Configuration

Ensure all settings are configured correctly

Check verification settingsReview role configurationVerify channel setup

Test Verification

Perform a test verification to identify issues

Use test accountMonitor verification processCheck error messages

Check Logs

Review system logs for error messages

Check dashboard logsReview Discord audit logMonitor bot activity

System Status Check

Before troubleshooting, check if there are any known issues with external services:

AkuWorks Status

Check our service status

Discord Status

Check Discord API status

Cloudflare Status

Check Turnstile status

Common Error Codes

Verification Errors

VER_001Challenge timeout

VER_002Invalid challenge response

VER_003Rate limit exceeded

Permission Errors

PERM_001Missing manage roles

PERM_002Role hierarchy issue

PERM_003Channel access denied

Still Need Help?

If you couldn't find a solution to your problem, our support team is here to help: