Troubleshooting

Solutions to common problems and error messages. If you don't find your issue here, visit our Support Server.

Common issues

Bot not responding to commands

Symptoms: You type a slash command but nothing happens, or commands don't appear in the slash command menu.

Solutions:

1. Check bot status: Make sure Clocky shows as "Online" (green dot) in the member list
2. Wait for Discord cache: After adding the bot, wait 1-5 minutes for commands to appear
3. Check permissions: Verify Clocky has "Send Messages" and "Use Slash Commands" permissions
4. Try in a different channel: Some channels may have permission overrides
5. Rejoin the server: On mobile especially, leaving and rejoining can refresh commands
6. Kick and re-invite: Remove Clocky and re-invite it

Commands not appearing in autocomplete

Symptoms: When you type /, Clocky's commands don't show up.

Solutions:

# Commands can take 1-5 minutes to appear after installation
# Be patient and try again in a few minutes

"Already checked in" error

Symptoms: You try to /checkin but get an error saying you're already checked in.

Cause: You can only be checked in to one server at a time.

Solution:

1. Run /status to see which server you're checked in to
2. If it's a different server, go there and run /checkout
3. Return to your desired server and run /checkin

Session auto-closed unexpectedly

Symptoms: Your session was automatically closed before you checked out.

Cause: Sessions auto-close after a configured period (default: 12 hours) to prevent inflated time tracking.

Solutions:

• Check auto-close setting: Ask an admin to run /admin-set-autoclose to see or change the duration
• Manual adjustment: If you were legitimately working, ask an admin to manually correct your session
• Best practice: Check out when you finish working, or use /break for temporary pauses

Stats showing incorrect time

Symptoms: Your /stats display doesn't match your expectations.

Common causes:

1. Break time excluded: Break time is NOT included in worked time (this is intentional)
2. Different time range: Make sure you're viewing the correct range (today/week/month/all)
3. Auto-closed sessions: Sessions closed by auto-close use check-in time + configured hours
4. Timezone differences: All times are in UTC; display might differ from your local time

Verify:

/history limit:10

Review your recent sessions to see actual check-in/check-out times and durations.

Unable to export data

Symptoms: /data-export fails or no DM received.

Solutions:

1. Enable DMs: Go to Privacy Settings → Allow direct messages from server members
2. Check spam/requests: The message might be in your Message Requests folder
3. Wait: Export processing can take 1-2 minutes for large datasets
4. Cooldown: You can only export once every 24 hours
5. Contact support: If still not working, join our support server

Error messages

"❌ You're not checked in"

When: You try /checkout or /break without being checked in first.

Solution: Run /checkin to start a session first.

"⚠️ User Limit Reached"

When: Server has reached maximum active users for its tier.

Current limits:

• Free: 5 users
• Premium: 100 users
• Pro/Lifetime: Unlimited

Solutions:

1. Ask server admin to upgrade via dashboard.clockybot.com
2. Wait for inactive users to be pruned (after data retention period)
3. Ask admin to manually clean up old users

"🔒 Permission Denied"

When: You try to use an admin command without "Manage Server" permission.

Solution: Only server administrators can use commands like:

• /admin-close-session
• /admin-set-autoclose
• /admin-configure-deletion
• /admin-review-deletion-requests
• /rate-limit-stats

"⏱️ Rate Limit Exceeded"

When: You've sent too many commands too quickly.

Current rate limits:

• Per-command cooldowns: 5-30 seconds
• Per-server limits: 60-300 commands/minute (tier-dependent)

Solution:

1. Wait for the cooldown to expire (shown in error message)
2. Consider upgrading for faster cooldowns (Premium: 50% faster)
3. Admins bypass rate limits

"❌ Database Error"

When: There's a temporary issue with the database connection.

Solutions:

1. Try again: Most database errors are temporary
2. Wait a minute: Circuit breaker may be recovering
3. Check status: Visit our status page (link in support server)
4. Report if persistent: Join support server to report ongoing issues

Installation problems

Bot immediately leaves after being added

Cause: Server might be blacklisted or there's an automatic moderation bot kicking it.

Solutions:

1. Check your server's moderation bot settings
2. Whitelist Clocky in your anti-bot systems
3. Ensure your server isn't on Discord's restricted list
4. Contact support if issue persists

Missing permissions error

Symptom: Bot added but shows as offline or errors mention missing permissions.

Required permissions:

• Send Messages
• Embed Links
• Use Slash Commands

Solution:

1. Go to Server Settings → Roles → Clocky
2. Enable the permissions listed above
3. Check channel-specific permission overrides
4. Re-invite the bot if needed

Command issues

/checkin hangs or times out

Solutions:

1. Check bot lag: Run /status to see if bot is responding
2. Database overload: Wait 30 seconds and try again
3. Server outage: Check our status page
4. Report if persistent: Join support server

/history shows no sessions

Possible causes:

1. You haven't checked in/out yet
2. Data retention period expired (Free: 1 year, Premium: 5 years, Pro: 10 years)
3. You ran /data-delete previously
4. Wrong server

Solution: Run /stats range:all-time to see if you have any recorded time.

/leaderboard is empty

Cause: Leaderboards are private by default. Users must opt-in.

Solution:

1. Run /public to add yourself to the leaderboard
2. Ask other server members to opt-in as well
3. Admins can check private stats with /stats user:@username

Data & privacy

Can't delete my data

Symptom: /data-delete doesn't work or data still appears.

Check:

1. Soft delete mode: Server might require admin approval
   • Ask admin to run /admin-review-deletion-requests
2. Confirmation required: You must click the confirmation button
3. Other servers: Data in other servers requires separate deletion requests

Data export file is empty or incomplete

Solutions:

1. Verify you've actually used the bot (run /stats range:all-time)
2. Check that you opened the correct JSON file
3. Data older than retention period is automatically deleted
4. Re-run /data-export (24-hour cooldown)

Concerned about privacy

Resources:

• Read our Privacy Policy
• Learn about GDPR Compliance
• See Data Export guide
• See Data Deletion guide
• Leaderboards are opt-in only (private by default)

Still need help?

If your issue isn't resolved:

1. Check FAQ: Visit our Frequently Asked Questions
2. Review documentation: Search our docs for specific topics
3. Join support server: Get live help from our team and community
4. Contact us directly: Use the contact form on our website