---
url: "https://docs.on-book.app/pro/user/troubleshooting.md"
description: "Common issues and solutions for On Book Pro users."
---

# Troubleshooting & FAQ

> **Common issues and solutions for On Book Pro users.**

***

## Common Issues

### Script Import

**Q: My PDF won't import. What's wrong?**

A: The AI script analyzer works best with:

* PDF format (text-based or scanned — both work)
* Standard theatrical formatting
* Clear character names and scene divisions

Try these steps:

1. Ensure the file is a PDF (the AI handles both text-based and scanned scripts)
2. Check that the file size is under 10MB for web upload, or 200MB via Cloud Storage relay
3. If import fails, try manually adding acts/scenes

***

**Q: The AI extracted incorrect character names.**

A: You can manually edit imported data:

1. Go to **Show Structure** → **Characters**
2. Edit names or merge duplicate entries
3. The AI uses pattern matching—unusual names may need correction

***

**Q: The import is taking a very long time.**

A: Large scripts (100+ pages) can take 1-3 minutes. The system uses a cloud relay for big files:

1. Wait for the progress indicator to complete
2. If it stalls, check your network connection
3. Try importing in smaller chunks if the full script fails

***

### Cloud Sync

**Q: My changes aren't syncing to my team.**

A: Check these items:

1. Verify you're online (offline changes sync automatically when reconnected)
2. Check presence indicators in the header to see who's online
3. Try refreshing the page to force a sync
4. Check the cloud status indicator for sync errors

***

**Q: I see a "permission denied" error.**

A: This usually means:

* You're not logged in to a Google account
* You don't have access to this project (ask the owner for an invite link)
* Your membership is still pending (owner needs to approve)
* You lack the specific permission for that action

**To fix:**

1. Sign out and sign back in
2. Ask the project owner to check your membership status
3. Request the appropriate role for your needs

***

**Q: I made changes but they disappeared!**

A: Changes may appear lost due to:

1. **Preserved write review**: Some edits are saved locally but held back from the shared project until you choose **Review** in the header.
2. **Sync conflict**: Another user's changes may have overwritten yours. Use Undo (Ctrl+Z) to recover where the feature supports it.
3. **Offline mode**: If you were offline, supported changes queue until reconnection. Ensure you're online.
4. **Browser issue**: Try hard-refreshing (Ctrl+Shift+R) to reload from server after confirming no preserved writes need review.

***

### Offline Mode

**Q: Does everything work offline?**

A: Not every feature has the same offline behavior. Supported edits are saved locally and sync when you reconnect; some preserved writes may require review before they apply to the shared project.

***

**Q: How do I know if I'm offline?**

A: Look for the offline indicator in the app header. The app automatically detects connection status and shows:

* 🟢 **Green**: Connected and synced
* 🟡 **Yellow**: Syncing or pending changes
* 🔴 **Red/Gray**: Offline

***

**Q: My offline changes didn't sync when I came back online.**

A: This is rare, but can happen if:

1. You were offline for an extended period
2. There were conflicting changes from other users
3. The browser cleared local storage
4. A preserved write is waiting under the **Review** button in the header

**To check:**

1. Open browser DevTools → Application → IndexedDB
2. Look for the On Book Pro database
3. If missing, your local data may have been cleared

***

### Permissions & Access

**Q: I can't see certain features or tabs.**

A: Features are filtered based on your role and workspace:

1. **Workspace filtering**: Some tools only appear in certain workspaces (Prep, Showtime, Reflect)
2. **Permission filtering**: Your role may not include access to that feature

**To check:**

1. Try the "All Tools" workspace to see everything available to your role
2. Ask a project admin what role you've been assigned
3. Request additional permissions if needed

***

**Q: I can see a feature but can't edit anything.**

A: You have VIEW permission but not EDIT permission. This is common for:

* Cast members viewing the schedule
* Crew viewing the run sheet
* Designers viewing budget info

Contact a Stage Manager or Owner to request edit access.

***

**Q: I'm an admin but can't access the Admin Portal.**

A: The full Admin Portal is currently limited to super admins. Project Owner or `MANAGE_USERS` access lets you manage project-level access where the current project settings surface allows it, but it does not expose `/admin` by itself.

To check:

1. Open **Settings** and look for **Administration**.
2. If you do not see it, ask the maker/operator to confirm whether your account is marked as a super admin.
3. For current-project member changes, use **Settings** → **Project Access** if that section appears for your role.

***

**Q: A team member can't claim their profile.**

A: Profile claiming requires email matching:

1. The email they sign in with must match the email in their personnel record
2. If emails do not match, ask a super admin to use **Admin Portal** → **Members** → **Link to Personnel**, or use the project-scoped access tools if they are available for your project role.
3. Manual linking bypasses email matching.

***

### Printing

**Q: The print output looks wrong or is missing content.**

A: Print issues can occur due to:

1. **Browser print settings**: Try "Print using system dialog" instead of browser preview
2. **Page size**: Ensure page size matches your document (Letter/A4)
3. **Margins**: Reduce margins if content is cut off
4. **Landscape vs Portrait**: Some reports work better in landscape

***

**Q: Print is cutting off table rows mid-row.**

A: Enable "Avoid breaking inside" in print settings, or:

1. Use a PDF export instead
2. Reduce zoom level before printing
3. Try a different browser (Chrome has best print support)

***

### PWA & Installation

**Q: How do I install On Book Pro as an app?**

A: On Book Pro is a Progressive Web App (PWA):

**Desktop (Chrome/Edge):**

1. Look for the install icon in the browser address bar
2. Click "Install" when prompted
3. The app appears in your Start Menu / Applications

**Mobile (iOS):**

1. Open in Safari
2. Tap the Share button
3. Select "Add to Home Screen"

**Mobile (Android):**

1. Open in Chrome
2. Tap the menu (⋮)
3. Select "Install app" or "Add to Home Screen"

***

**Q: The app feels stuck on an old version.**

A: The PWA caches content for offline use. To force update:

1. **Soft refresh**: Pull down to refresh (mobile) or F5 (desktop)
2. **Hard refresh**: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
3. **Clear cache**: Browser Settings → Clear browsing data → Cached images and files
4. **Reinstall**: Uninstall the PWA and reinstall from the browser

***

### Sound & Audio

**Q: Sounds won't play.**

A: Check:

1. **Browser autoplay policy**: Interact with the page first (click anywhere)
2. **Volume settings**: Check master volume and individual clip volume
3. **File format**: Ensure your files are MP3, WAV, or OGG
4. **Browser support**: Try Chrome for best audio compatibility

***

**Q: Downloaded sounds aren't available offline.**

A: Sounds must be fully downloaded to work offline:

1. Play each sound once while online to cache it
2. Check browser storage settings—some browsers limit cache size
3. Large sound libraries may exceed cache limits

***

### Account & Profile

**Q: I can't update my profile information.**

A: Profile editing requires:

1. Being signed in
2. Having a personnel record linked to your account
3. Having the UPDATE\_OWN\_PROFILE permission (Cast and above)

If you see read-only fields, ask a Stage Manager to update them for you.

***

**Q: My profile changes aren't showing in the Personnel Directory.**

A: Changes should sync automatically. If not:

1. Refresh the page
2. Check that your account is linked to the correct personnel record
3. Ask a project access manager or super admin to verify the personnel link.

***

**Q: I see old data from a previous session after logging out and back in.**

A: This is rare and usually resolves itself. Try:

1. **Log out** from your profile modal
2. **Hard refresh** the page (Ctrl+Shift+R)
3. If stale data persists, clear your browser's site data for on-book.app:
   * Chrome: Settings → Privacy → Site Settings → on-book.app → Clear Data
   * Or open DevTools → Application → Storage → Clear Site Data

## Still Need Help?

If your issue isn't listed here:

1. Check the [User Guide](./index.md) for feature-specific help
2. Review the [Feature Guides](./features/overview.md) for detailed instructions
3. Report a bug via [GitHub Issues](https://github.com/your-org/on-book-pro/issues)

***

*Last updated: May 17, 2026*