> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inkwell.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common issues and recover from errors.

This guide helps you diagnose and fix common Inkwell issues. If you can't find a solution here, contact support.

## Script Won't Open

This guide helps you diagnose and fix common Inkwell issues. If you can't find a solution here, contact support at **[support@inkwell.app](mailto:support@inkwell.app)**.

## Script Won't Open

### Problem: "File is corrupted" or cannot be read

**Possible causes**:

* File transfer was interrupted
* Disk storage error
* File was manually edited outside Inkwell with syntax errors

**Solutions**:

<Steps>
  <Step title="Check version history">
    Inkwell keeps local checkpoints of your work. Open the folder containing your screenplay and check for a hidden `.ink-history` directory (press `Cmd+Shift+.` in Finder to toggle hidden files). Find the most recent `.ink` file backup, duplicate it, and rename it to restore your draft.
  </Step>

  <Step title="Try opening in a text editor">
    Your `.ink` file is formatted as standard text (Fountain/JSON). You can open it in TextEdit to recover your screenplay's text directly.
  </Step>

  <Step title="Contact support">
    If you cannot recover your screenplay, email it to **[support@inkwell.app](mailto:support@inkwell.app)**. Our engineering team can often repair damaged structures to retrieve your writing.
  </Step>
</Steps>

### Problem: "File format not recognized"

**Cause**: Trying to open a file that is not a native `.ink` project.

**Solution**: Inkwell uses the `.ink` project package format. To open scripts written in other apps, use **File → Import** and select **PDF…**, **Fountain…**, or **Final Draft…**.

***

## Quill AI Issues

### Problem: "Insufficient credits" error

**Cause**: Your monthly Quill AI credit allocation is depleted.

**Solutions**:

* Wait until your billing date (Pro) or the 1st of the month (Free) for credits to reset.
* Purchase a credit pack (**Inkwell → Settings…** → **Account** → **Buy Credits**).
* Upgrade to Pro (**Inkwell → Settings…** → **Account** → **Upgrade to Pro**).

### Problem: Quill AI won't open or load

**Possible causes**:

* Internet connection is offline (Quill requires an internet connection).
* Network firewall or VPN is blocking the API request.

**Solutions**:

<Steps>
  <Step title="Check internet connection">
    Verify that your Mac is connected to the internet.
  </Step>

  <Step title="Toggle Quill Panel">
    Press `Cmd+]` to close and reopen the Quill AI panel to force a reconnection attempt.
  </Step>

  <Step title="Check for updates">
    Go to **Inkwell → Check for Updates…** to ensure you are running the latest desktop client.
  </Step>
</Steps>

***

## Formatting Issues

### Problem: Text won't format as dialogue

**Cause**: Inkwell auto-detects element types based on screenplay formatting conventions.

**Solutions**:

* Character names must be in ALL CAPS on their own line.
* Dialogue must follow directly on the line below the character's name.
* Do not leave blank lines between the character name and their dialogue.

***

## Performance & Display Issues

### Problem: Screenplay rendering feels laggy

**Solutions**:

* **Disable typewriter scrolling**: Turn off typewriter scrolling via **View → Typewriter Scrolling** to reduce vertical page jumps during heavy edits.
* **Adjust zoom**: Reset your zoom to 100% (`Cmd+Opt+0`) to reduce GPU rendering load.
* **Restart Inkwell**: Quit the app (`Cmd+Q`) and reopen it to flush temporary memory.

***

## Auto-Save Issues

### Problem: Save indicator shows an error

**Possible causes**:

* Disk permissions issue.
* Drive where script is stored was disconnected (e.g., an external drive or cloud drive).

**Solutions**:

* Try saving to a new location using **File → Export**.
* Move your script folder to your local **Documents** folder to resolve permissions issues.
* Manually trigger a save with `Cmd+S`.

***

## General Recovery Steps

### Lost Work Recovery

<Steps>
  <Step title="Check script history">
    Open Finder, go to the folder where your script is saved, and look for the `.ink-history` directory. This contains automatic checkpoints of your writing.
  </Step>

  <Step title="Check Time Machine">
    If you use macOS Time Machine, you can roll back your script folder to an earlier hour.
  </Step>
</Steps>

### Resetting App Settings

If you experience persistent configuration issues, you can reset Inkwell's preferences back to factory defaults:

<Warning>
  This will reset your custom themes, shortcuts, and settings, but it will **never** delete your screenplay files.
</Warning>

1. Quit Inkwell (`Cmd+Q`).
2. Open the **Terminal** app on your Mac.
3. Paste the following command and press Enter:
   ```bash theme={null}
   defaults delete tech.rundquist.InkwellEditor
   ```
4. Reopen Inkwell.

***

## Get Help

If your issue persists:

* **Email Support**: [support@inkwell.app](mailto:support@inkwell.app)
* **Updates**: Check **Inkwell → Check for Updates…** (or the Mac App Store updates tab).

***

## Next Steps

<CardGroup cols={2}>
  <Card title="FAQ" icon="question" href="/reference/faq">
    Common questions and answers
  </Card>

  <Card title="Keyboard Shortcuts" icon="keyboard" href="/reference/keyboard-shortcuts">
    Master Inkwell shortcuts
  </Card>
</CardGroup>