Common Issues & Solutions

Quick Fix Finder: Find solutions to the top 20 most common issues with Scrollbook and Cipher.

Can't find your issue?

• Full FAQ - Comprehensive Q&A
• Discord Support - Community help
• Contact Support - Direct assistance

Table of Contents

• Discord Bot Issues
• Web App Issues
• Character Issues
• Session Issues
• Authentication Issues
• Performance Issues

Discord Bot Issues

Issue #1: Cipher Bot Not Responding

Symptoms: Bot doesn't reply to commands, appears offline

Quick Fix:

1. Check bot status (should be green/online)
2. Try /ping command
3. Verify bot has channel permissions
4. Check AI hours available with /hours

Detailed Solutions:

A. Bot Offline

• Check Status Page for outages
• Wait 5-10 minutes for bot restart
• If persistent, report issue

B. Permission Issues

1. Discord → Server Settings → Roles
2. Find "Cipher" role
3. Verify permissions:
   • Send Messages
   • Read Message History
   • Use Slash Commands
   • Embed Links
   • Add Reactions

C. No AI Hours

/hours

If 0 hours remaining:

• Purchase hour pack
• Upgrade tier
• Wait for monthly reset

Success Check:

/ping

Should respond: " Pong! Latency: Xms"

Issue #2: "Command Not Found" Error

Symptoms: /command shows "Command not found" or no autocomplete

Quick Fix:

1. Type "/" and wait 2 seconds for autocomplete
2. Ensure spelling is correct
3. Check you're in server where bot is added
4. Verify bot has Use Slash Commands permission

Common Mistakes:

Wrong: /charactersheet (no hyphen) Right: /character-sheet

Wrong: /askcipher (no hyphen) Right: /ask-cipher

Solutions:

A. Autocomplete Not Showing

1. Click in message box
2. Type "/"
3. Wait 2-3 seconds
4. Scroll through command list

B. Commands Changed Recently

• Restart Discord app
• Clear Discord cache
• Re-authorize bot

C. Bot Not in Server

• Re-invite bot
• Authorize with correct server

Issue #3: Cipher Gives Wrong or Outdated Information

Symptoms: Cipher references old NPCs, wrong campaign info, or contradicts established lore

Quick Fix:

/cipher-clear-memory

This resets conversation context.

When This Happens:

• Switching between campaigns
• After importing old data
• When Cipher seems "confused"

Prevention:

• Use different channels for different campaigns
• Clear memory between sessions if needed
• Provide context when switching topics

Example:

DM: Clear memory, we're starting a new campaign arc.
/cipher-clear-memory

DM: We're now in the Feywild, not the Material Plane anymore.

Issue #4: "No Active Campaign" Error

Symptoms: Commands fail with "Please select an active campaign"

Quick Fix:

/select-campaign

Choose your campaign from the list.

Why This Happens:

• First time using bot in this server
• Switched between multiple campaigns
• Campaign was archived/deleted

Verification:

/current-campaign

Should show active campaign details.

Still Not Working?

/list-campaigns

If no campaigns listed:

1. Create campaign in Scrollbook
2. Wait 30 seconds for sync
3. Try /select-campaign again

Web App Issues

Issue #5: Character Sheet Not Updating

Symptoms: Changes in Discord don't appear in Scrollbook (or vice versa)

Quick Fix:

1. Refresh page (Cmd/Ctrl + R)
2. Wait 30 seconds for sync
3. Use /sync-character in Discord
4. Clear browser cache

Step-by-Step:

A. Force Refresh

• Mac: Cmd + Shift + R
• Windows: Ctrl + F5
• Linux: Ctrl + Shift + R

B. Force Sync from Discord

/character-update

Make any small change (e.g., add 1 HP) to trigger sync.

C. Clear Browser Cache

1. Browser Settings
2. Privacy/Security
3. Clear browsing data
4. Select "Cached images and files"
5. Clear data

D. Check Connection

• Are you online?
• Try different page to verify internet
• Check Status Page

Prevention:

• Keep browser tab open during sessions
• Don't make simultaneous changes in both places
• Let one change finish syncing before making another

Issue #6: Scrollbook Loading Slowly

Symptoms: Pages take 5+ seconds to load, UI feels sluggish

Quick Diagnostics:

# Check internet speed
# Should be >10 Mbps for smooth experience
speedtest.net

Quick Fixes:

A. Browser Issues

1. Close unnecessary tabs (free up memory)
2. Disable browser extensions
3. Try incognito/private mode
4. Use Chrome or Firefox (recommended browsers)

B. Network Issues

• Switch to different WiFi network
• Use mobile hotspot to test
• Reset router

C. Clear Data

1. Clear browser cache (see #5)
2. Log out and log back in
3. Try different browser

D. Device Issues

• Close other apps (free up RAM)
• Restart computer
• Update browser to latest version

Benchmarks:

Still Slow?

• Report issue with details:
  • Browser + version
  • Internet speed test results
  • Which pages are slow

Issue #7: Can't Create Campaign

Symptoms: "Create Campaign" button disabled or fails

Quick Diagnostics:

Check your tier limits:
- Free Adventurer: 0 campaigns (can join only)
- Single Campaign: 1 campaign
- Multi-Campaign: 3 campaigns
- Unlimited Guild: Unlimited

Solutions:

A. Tier Limit Reached

View your campaigns:

1. Dashboard → Campaigns
2. Count active campaigns
3. If at limit:
   • Archive old campaigns
   • Upgrade tier

B. Discord Server Not Linked

1. Dashboard → Link Server
2. Select Discord server
3. Authorize connection
4. Try creating campaign again

C. Missing Permissions

Discord server requirements:

• Must have "Manage Server" permission
• Or be server owner

D. Validation Errors

Required fields:

• Campaign name (1-255 chars)
• Discord server selected
• Starting level (1-20)

Optional but recommended:

• Description
• Era/setting
• Tone

Character Issues

Issue #8: Character Not Appearing in Discord

Symptoms: Created character in Scrollbook but can't see it with /character-list

Quick Fix:

1. Wait 30 seconds for sync
2. Use /character-list in Discord
3. Verify you're in correct server/campaign
4. Force sync with /sync-character

Step-by-Step:

A. Verify Creation

1. Go to Scrollbook Characters
2. Is character listed?
3. Check which campaign it's linked to

B. Check Campaign

/current-campaign

Character must be in active campaign to appear.

C. Force Sync

/select-campaign
[Choose campaign with your character]

/character-list show_all: True

D. Link Character to Campaign

If character exists but not in campaign:

1. Scrollbook → Character
2. Edit character
3. Add to campaign
4. Save

Still Not Working?

Create character again using /character-create in Discord.

Issue #9: Can't Level Up Character

Symptoms: "Level Up" button disabled or command fails

Common Causes:

A. Insufficient XP

Check XP requirements:

Solution:

/character-sheet character_name: [name]

Check current XP vs requirement.

B. Milestone Leveling

If campaign uses milestone:

• DM controls leveling
• XP not tracked
• DM must manually level you up

Solution: Ask DM to level your character.

C. Character Locked

Some campaigns lock characters during sessions.

Solution: Wait for session to end.

D. Web App vs Discord Mismatch

Try leveling in the other platform:

• If web app fails → try Discord
• If Discord fails → try web app

Issue #10: Inventory Not Saving

Symptoms: Added items disappear after refresh

Quick Fix:

1. Add item
2. Wait 3 seconds
3. Look for "Saved" indicator
4. Refresh to verify

Common Mistakes:

Adding too quickly

• Add item
• Immediately add another
• First item lost

Correct approach:

• Add item
• Wait for save confirmation
• Then add next item

Closing page immediately

• Add items
• Close browser
• Changes not synced

Correct approach:

• Add items
• Wait 5-10 seconds
• Then close

Solutions:

A. Disable Browser Auto-Refresh

• Some extensions refresh pages automatically
• Disable for scrollbook.app

B. Check Internet Connection

• Poor connection = failed saves
• Wait for stable connection

C. Use Discord Alternative

/character-update

Update inventory via Discord instead.

Session Issues

Issue #11: Session Summary Not Generating

Symptoms: Ended session but no summary appeared

Quick Diagnostics:

A. Session Too Short

• Minimum: 10 minutes
• AI won't generate summary for very short sessions

B. No AI Hours

/hours

If 0 hours, summary won't generate.

C. Processing Delay

• Wait 5-10 minutes
• Summary generation takes time

Solutions:

Manual Trigger:

/session-summary

This re-requests summary generation.

Check Session History:

1. Scrollbook → Sessions
2. Click on latest session
3. Look for summary section

If Still Missing:

• Check spam/other Discord channels
• Summary may have been posted elsewhere
• Contact support with session ID

Issue #12: Can't Start Session

Symptoms: /start-session fails or shows error

Common Causes:

A. Session Already Active

/session-summary

Check if session is already running.

Solution:

/end-session

Then start new session.

B. No Active Campaign

/select-campaign

Solution: Select campaign first.

C. Not the DM

• Only campaign DM can start sessions
• Players can't use /start-session

Solution: Ask DM to start session.

D. No AI Hours

/hours

Need at least 0.1 hours to start.

Solution:

• Purchase hour pack
• Upgrade tier

Authentication Issues

Issue #13: Can't Log In

Symptoms: Login fails, "Invalid credentials" error

Quick Fix:

A. Use Discord OAuth

Scrollbook uses Discord for login:

1. Click "Sign in with Discord"
2. Authorize Scrollbook
3. Redirect to dashboard

You don't set a password - Discord handles auth.

B. Clear Cookies

1. Browser Settings
2. Privacy → Cookies
3. Clear scrollbook.app cookies
4. Try logging in again

C. Try Different Browser

Test in:

• Chrome
• Firefox
• Safari
• Edge

D. Check Discord Account

• Can you log into Discord?
• Is your Discord account verified?

Issue #14: "Unauthorized" API Errors

Symptoms: API requests fail with 401 error

For API Users (Multi-Campaign+ tier):

A. Token Expired

Tokens expire after 30 days.

Solution:

1. Scrollbook → Settings → API
2. Generate new token
3. Update your code

B. Token Format Wrong

// ✅ Correct
Authorization: Bearer sk_live_abc123xyz789

// ❌ Wrong
Authorization: sk_live_abc123xyz789  // Missing "Bearer"

C. Token Deleted

Check API tokens page - was it deleted?

Solution: Generate new token.

D. Wrong Environment

• Development token won't work in production
• Verify you're using correct API URL

Performance Issues

Issue #15: High AI Hour Usage

Symptoms: Running out of AI hours faster than expected

Diagnosis:

Track usage:

/hours

Shows:

• Hours remaining
• Hours used this month
• Usage rate

Common Causes:

A. Forgot to End Session

/pause-session  # During breaks
/end-session    # When done

Active sessions drain hours continuously.

B. Multiple Active Sessions

• Only run one session at a time
• End old sessions before starting new

C. Long Sessions

• 4-hour session = ~3.5 AI hours
• Consider splitting into shorter sessions

Optimization Tips:

Minimize Usage:

• Use /pause-session during breaks
• End sessions promptly
• Use simple dice rolling (doesn't use AI)

Maximize Value:

• Use Cipher for narration (high value)
• Let Cipher handle combat (saves time)
• Get session summaries (huge value)

Issue #16: Dice Rolls Not Working

Symptoms: /roll command fails or gives unexpected results

Common Issues:

A. Invalid Dice Notation

✅ Valid:
/roll dice: 1d20
/roll dice: 2d6+3
/roll dice: 1d20+5
/roll dice: 4d6
/roll dice: d100

❌ Invalid:
/roll dice: 20  # Missing "d"
/roll dice: 1d20 + 5  # Spaces not allowed
/roll dice: 2d6 + 3d4  # Multiple dice types (use separate rolls)

B. Modifier Format

✅ Correct:
/roll dice: 1d20+5
/roll dice: 2d6-2

❌ Wrong:
/roll dice: 1d20 + 5  # Spaces
/roll dice: 1d20+5.5  # Decimals

C. Range Issues

Limits:

• Max dice: 100
• Max sides: 1000
• Max modifier: ±1000

Example:

/roll dice: 1000d1000  # Will fail (too large)

Issue #17: Notifications Not Working

Symptoms: Not receiving Discord notifications for:

• Session invitations
• Character level ups
• Campaign invitations

Solutions:

A. Discord Notification Settings

1. User Settings → Notifications
2. Enable "Direct Messages"
3. Enable "Server Notifications"

B. Scrollbook Notification Settings

1. Scrollbook → Settings → Notifications
2. Enable:
   • Session invitations
   • Character updates
   • Campaign invitations
3. Choose delivery: Discord DMs, Email, or Both

C. Discord DMs Blocked

Privacy settings may block DMs from Scrollbook.

Solution:

1. Server Settings → Privacy & Safety
2. Enable "Allow direct messages from server members"

D. Check Spam/Other

• Notifications may be in Discord "Other" tab
• Check Discord notification settings

Data & Sync Issues

Issue #18: Lost Data / Changes Reverted

Symptoms: Made changes but they disappeared

Immediate Action:

Don't panic! Data is likely safe.

A. Check Version History

Scrollbook may have auto-saved:

1. Character/Campaign page
2. Look for "History" or "Versions"
3. Restore previous version

B. Force Sync

/sync-character

This pulls latest from server.

C. Check Other Device

If you use multiple devices:

• Phone may have cached version
• Check there before saving over

D. Export Backup

Regular backups prevent this:

1. Settings → Data Export
2. Download JSON backup
3. Store safely

Prevention:

• Wait for "Saved" indicator
• Don't close browser immediately
• Export backups monthly

Issue #19: Homebrew Content Not Appearing

Symptoms: Created homebrew but can't use it in characters

Diagnostics:

A. Check Publish Status

Homebrew must be published:

1. Templates → [Your Homebrew]
2. Status: "Published" (not "Draft")

B. Check Scope

Who can see it?

• Private: Only you
• Campaign: Campaign members
• Server: Server members
• Public: Everyone

Solution: Change scope to appropriate level.

C. Campaign Settings

Campaign must allow homebrew:

1. Campaign → Settings
2. "Allow Homebrew Content": Enabled
3. Select sources:
   • Your homebrew
   • Campaign homebrew
   • Server homebrew

D. Refresh Lists

1. Clear browser cache
2. Restart Discord
3. Re-select campaign

Issue #20: "Rate Limit Exceeded" Error

Symptoms: API requests fail with 429 error

For API Users:

Rate Limits by Tier:

Solutions:

A. Implement Exponential Backoff

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const wait = Math.pow(2, i) * 1000;  // 1s, 2s, 4s
        await sleep(wait);
        continue;
      }
      throw error;
    }
  }
}

B. Respect Retry-After Header

if (error.status === 429) {
  const retryAfter = error.headers['retry-after'];
  await sleep(retryAfter * 1000);
  // Retry request
}

C. Batch Requests

Instead of 100 individual requests, batch into 10 requests.

D. Cache Responses

Don't re-fetch data that rarely changes:

• Campaign settings
• Character sheets (cache for 5 min)
• Content library (cache for 1 hour)

E. Upgrade Tier

If legitimate high usage:

• Contact sales for Enterprise plan
• Custom rate limits available

Getting More Help

Before Contacting Support

Gather this information:

• Error message (exact text or screenshot)
• What you were trying to do
• Steps to reproduce the issue
• Browser/device (if web app issue)
• Discord username and server
• When it started happening
• What you've already tried

Where to Get Help

1. Documentation

• FAQ - Comprehensive Q&A
• All Docs - Complete documentation

2. Community

• Discord Server - Fast community help
• Forum - Searchable Q&A

3. Support

• Contact Form - Submit ticket
• Response time: 24-48 hours

4. Report Bugs

• GitHub Issues
• For confirmed bugs only

Related Documentation

• FAQ - Frequently asked questions
• Discord Bot Commands - All bot commands
• Web App Guide - Using Scrollbook
• API Reference - API documentation

Last Updated: 2025-12-05 Version: 1.0 Maintained by: Support Team Issues resolved: 10,000+ tickets