> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtr46/meikipop/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues and problems you may encounter while using meikipop.

This guide covers common issues and their solutions. If you encounter a problem not listed here, please [open an issue on GitHub](https://github.com/rtr46/meikipop/issues).

## Dictionary issues

<Accordion title="Dictionary file not found">
  **Error message:** `ERROR: Dictionary file 'jmdict_enhanced.pkl' not found`

  **Cause:** The prebuilt dictionary is missing from your installation.

  **Solution:**

  <Steps>
    <Step title="Download prebuilt dictionary">
      Download the latest release from [GitHub releases](https://github.com/rtr46/meikipop/releases/latest) which includes the prebuilt dictionary.
    </Step>

    <Step title="Or build your own">
      If running from source, build the dictionary manually:

      ```bash theme={null}
      pip install lxml
      python -m scripts.build_dictionary
      ```

      This will create `jmdict_enhanced.pkl` in your repository root.
    </Step>

    <Step title="Verify the file location">
      Ensure `jmdict_enhanced.pkl` is in the same directory as the meikipop executable or `src/main.py` file.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Dictionary loading is slow">
  **Symptom:** Dictionary takes more than 10 seconds to load on startup.

  **Possible causes:**

  * Using JSON dictionary files instead of the pickled format
  * Dictionary file is corrupted
  * Disk I/O bottleneck (slow hard drive)

  **Solution:**

  1. Ensure you're using `jmdict_enhanced.pkl` (pickled format), not JSON files
  2. Rebuild the dictionary if it may be corrupted:
     ```bash theme={null}
     python -m scripts.build_dictionary
     ```
  3. Move meikipop to an SSD if currently on a slow hard drive
  4. Check console output for the actual load time: "Dictionary loaded in X.XX seconds"

  <Info>
    Normal load times are 1-3 seconds on modern systems. Anything over 5 seconds indicates an issue.
  </Info>
</Accordion>

<Accordion title="No results or wrong results">
  **Symptom:** Dictionary lookups return no results or incorrect definitions.

  **Possible causes:**

  * Dictionary version mismatch
  * Corrupted dictionary file
  * OCR not recognizing text correctly

  **Solution:**

  1. First, verify OCR is working by checking what text is being recognized (watch console output with debug logging)
  2. Try looking up a known common word like 日本 or これ
  3. Rebuild the dictionary from scratch:
     ```bash theme={null}
     rm jmdict_enhanced.pkl
     python -m scripts.build_dictionary
     ```
  4. Check that your meikipop version matches the dictionary format
</Accordion>

## OCR issues

<Accordion title="Google Lens OCR not working">
  **Symptom:** No popup appears, or console shows OCR errors.

  **Possible causes:**

  * No internet connection
  * Firewall blocking requests to Google
  * API key issues
  * Network timeout

  **Solution:**

  <Steps>
    <Step title="Check internet connection">
      Verify you can access `https://lensfrontend-pa.googleapis.com`
    </Step>

    <Step title="Check firewall settings">
      Ensure meikipop is allowed through your firewall and can make HTTPS connections.
    </Step>

    <Step title="Try a different OCR provider">
      Switch to a local provider to isolate the issue:

      * Right-click system tray icon → OCR Provider → meikiocr (local)
    </Step>

    <Step title="Check console for errors">
      Look for "OCR Request Failed" messages that might provide more details.
    </Step>
  </Steps>

  <Tip>
    If Google Lens consistently fails, consider switching to meikiocr (local) for reliable offline operation.
  </Tip>
</Accordion>

<Accordion title="owocr websocket connection failed">
  **Error message:** `Could not connect to owocr at ws://127.0.0.1:7331`

  **Cause:** owocr is not running or not configured correctly.

  **Solution:**

  1. Ensure owocr is installed and up to date:
     ```bash theme={null}
     pip install -U "owocr>=1.15"
     ```

  2. Start owocr with the correct parameters:
     ```bash theme={null}
     owocr -r websocket -w websocket -of json -e glens
     ```

  3. Verify owocr is running:
     ```bash theme={null}
     # Should show owocr listening on port 7331
     netstat -an | grep 7331
     ```

  4. Check that you're using a compatible owocr backend (glens, oneocr, apple, or bing)

  <Warning>
    owocr versions older than 1.15.0 do not support the websocket protocol required by meikipop.
  </Warning>
</Accordion>

<Accordion title="Chrome Screen AI missing components">
  **Error message:** `Please download the screenai component...`

  **Cause:** Screen AI library files are not installed.

  **Solution:**

  <Steps>
    <Step title="Download Screen AI components">
      Visit [Chrome's infrastructure packages](https://chrome-infra-packages.appspot.com/p/chromium/third_party/screen-ai) and download the appropriate version for your platform.
    </Step>

    <Step title="Extract to correct location">
      Extract the contents to:

      * Linux: `~/.config/screen_ai/resources/`
      * Windows: `%USERPROFILE%\.config\screen_ai\resources\`
    </Step>

    <Step title="Verify files are present">
      Ensure `chrome_screen_ai.dll` (Windows) or `libchromescreenai.so` (Linux) is in the resources directory.
    </Step>

    <Step title="Restart meikipop">
      The provider will automatically initialize with the new components.
    </Step>
  </Steps>
</Accordion>

<Accordion title="meikiocr initialization failed">
  **Error message:** `failed to initialize meikiocr (local)`

  **Possible causes:**

  * meikiocr library not installed
  * Model download failed
  * Incompatible system configuration

  **Solution:**

  1. Install or update meikiocr:
     ```bash theme={null}
     pip install -U meikiocr
     ```

  2. Ensure you have sufficient disk space for model downloads (\~200MB)

  3. Check that your system has:
     * CUDA support (for GPU acceleration), or
     * CoreML support (macOS), or
     * CPU fallback capability

  4. Check console output for specific error details

  5. Try running from source to see detailed error messages
</Accordion>

## Platform-specific issues

<Accordion title="macOS: Tray icon not showing">
  **Symptom:** System tray icon doesn't appear on macOS.

  **Cause:** macOS tray support is in beta and may not work reliably.

  **Solution:**

  1. Configure meikipop through `config.ini` directly instead of the GUI:
     ```ini theme={null}
     [Settings]
     hotkey = shift
     scan_region = region
     ocr_provider = meikiocr (local)
     ```

  2. Use keyboard shortcuts and hotkeys to interact with meikipop

  3. Check console for any tray-related error messages

  <Note>
    macOS support is experimental. If you encounter issues, please report them on GitHub to help improve compatibility.
  </Note>
</Accordion>

<Accordion title="macOS: Permission denied errors">
  **Symptom:** meikipop crashes or can't capture screen.

  **Cause:** Required macOS permissions not granted.

  **Solution:**

  <Steps>
    <Step title="Open System Preferences">
      Go to **System Preferences** → **Security & Privacy** → **Privacy**
    </Step>

    <Step title="Grant Input Monitoring permission">
      Add your terminal app (Terminal.app, iTerm, etc.) to **Input Monitoring** and enable it.
    </Step>

    <Step title="Grant Screen Recording permission">
      Add your terminal app to **Screen Recording** and enable it.
    </Step>

    <Step title="Grant Accessibility permission">
      Add your terminal app to **Accessibility** and enable it.
    </Step>

    <Step title="Restart terminal and meikipop">
      Close your terminal completely and reopen it, then start meikipop again.
    </Step>
  </Steps>
</Accordion>

<Accordion title="Linux: X11 vs Wayland issues">
  **Symptom:** Screen capture not working on Linux.

  **Cause:** meikipop currently only supports X11, not Wayland.

  **Solution:**

  1. Check if you're running Wayland:
     ```bash theme={null}
     echo $XDG_SESSION_TYPE
     ```

  2. If it shows "wayland", switch to X11:
     * Log out
     * At the login screen, select your username
     * Click the gear icon and choose "GNOME on Xorg" (or similar X11 option)
     * Log in

  3. Alternatively, run Xwayland apps in compatibility mode

  <Warning>
    Wayland support is planned but not yet implemented. X11 is currently required.
  </Warning>
</Accordion>

<Accordion title="Windows: Antivirus false positive">
  **Symptom:** Antivirus software blocks or deletes meikipop executable.

  **Cause:** Some antivirus programs flag meikipop as suspicious due to screen capture functionality.

  **Solution:**

  1. Add meikipop to your antivirus whitelist/exclusions
  2. Download from official GitHub releases only
  3. Verify file integrity if concerned
  4. Run from source instead of using the packaged executable:
     ```bash theme={null}
     python -m src.main
     ```

  <Info>
    meikipop requires screen capture permissions which some antivirus software may flag. The official releases are safe.
  </Info>
</Accordion>

## Performance issues

<Accordion title="Slow lookup or lag">
  **Symptom:** Significant delay between pressing hotkey and popup appearing.

  **Possible causes:**

  * Slow OCR provider
  * Network latency (Google Lens)
  * Large scan region
  * System resource constraints

  **Solution:**

  1. **Switch to a faster OCR provider:**
     * Try meikiocr (local) for fastest local processing
     * Enable Google Lens low bandwidth mode if using remote OCR

  2. **Reduce scan region size:**
     * Use region mode instead of fullscreen
     * Select a smaller area covering just the text you need
     * Right-click tray icon → Reselect Region

  3. **Enable auto scan mode:**
     * This pre-scans continuously for instant lookups
     * Right-click tray icon → Auto Scan Mode

  4. **Close other resource-intensive applications**

  5. **Check console output for timing information:**
     * Look for "OCR response received in X.XXs"
     * Identify which step is slow (OCR vs lookup vs rendering)
</Accordion>

<Accordion title="High CPU or memory usage">
  **Symptom:** meikipop uses excessive system resources.

  **Possible causes:**

  * Auto scan mode enabled with high frequency
  * Large scan region with continuous scanning
  * Memory leak (rare)

  **Solution:**

  1. Disable or adjust auto scan mode:
     ```ini theme={null}
     [Settings]
     auto_scan_mode = false
     auto_scan_interval_seconds = 1.0  # Increase interval
     ```

  2. Use region mode instead of fullscreen scanning

  3. Reduce scan region to the minimum needed area

  4. Try a different OCR provider (some are more resource-intensive)

  5. Restart meikipop if memory usage grows over time
</Accordion>

## Configuration issues

<Accordion title="Settings not saving">
  **Symptom:** Changes made in settings dialog don't persist after restart.

  **Possible causes:**

  * File permission issues
  * config.ini in wrong location
  * Syntax errors in config.ini

  **Solution:**

  1. Check that `config.ini` exists in the same directory as meikipop

  2. Verify file permissions (should be readable and writable)

  3. Look for syntax errors in config.ini:
     ```ini theme={null}
     # Correct format
     [Settings]
     hotkey = shift

     # Not like this
     hotkey: shift  # Wrong - use = not :
     ```

  4. Reset to defaults by deleting `config.ini` and restarting meikipop

  5. Check console output for "Settings saved to config.ini" confirmation
</Accordion>

<Accordion title="Hotkey not working">
  **Symptom:** Pressing the configured hotkey doesn't trigger lookups.

  **Possible causes:**

  * Hotkey conflict with another application
  * Invalid hotkey configuration
  * Permissions issue (macOS)

  **Solution:**

  1. Try a different hotkey:
     ```ini theme={null}
     [Settings]
     hotkey = ctrl
     # or
     hotkey = alt
     ```

  2. Check for conflicts with other applications using the same hotkey

  3. On macOS, ensure Input Monitoring permission is granted

  4. Restart meikipop after changing hotkey configuration

  5. Try using auto scan mode as an alternative to hotkey-triggered scanning
</Accordion>

## Getting help

If your issue isn't covered here:

1. **Check the console output** for error messages and stack traces
2. **Search existing GitHub issues** at [github.com/rtr46/meikipop/issues](https://github.com/rtr46/meikipop/issues)
3. **Open a new issue** with:
   * Your operating system and version
   * meikipop version
   * OCR provider being used
   * Relevant console output
   * Steps to reproduce the issue

<Tip>
  Run meikipop from source (`python -m src.main`) to see detailed console output which can help diagnose issues.
</Tip>