Skip to main content
This guide covers common issues and their solutions. If you encounter a problem not listed here, please open an issue on GitHub.

​
Dictionary issues

Error message: ERROR: Dictionary file 'jmdict_enhanced.pkl' not foundCause: The prebuilt dictionary is missing from your installation.Solution:
1

Download prebuilt dictionary

Download the latest release from GitHub releases which includes the prebuilt dictionary.
2

Or build your own

If running from source, build the dictionary manually:
pip install lxml
python -m scripts.build_dictionary
This will create jmdict_enhanced.pkl in your repository root.
3

Verify the file location

Ensure jmdict_enhanced.pkl is in the same directory as the meikipop executable or src/main.py file.
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: 
    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”
Normal load times are 1-3 seconds on modern systems. Anything over 5 seconds indicates an issue.
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: 
    rm jmdict_enhanced.pkl
python -m scripts.build_dictionary
  4. Check that your meikipop version matches the dictionary format

​
OCR issues

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:
1

Check internet connection

Verify you can access https://lensfrontend-pa.googleapis.com
2

Check firewall settings

Ensure meikipop is allowed through your firewall and can make HTTPS connections.
3

Try a different OCR provider

Switch to a local provider to isolate the issue:
  • Right-click system tray icon → OCR Provider → meikiocr (local)
4

Check console for errors

Look for “OCR Request Failed” messages that might provide more details.
If Google Lens consistently fails, consider switching to meikiocr (local) for reliable offline operation.
Error message: Could not connect to owocr at ws://127.0.0.1:7331Cause: owocr is not running or not configured correctly.Solution:
  1. Ensure owocr is installed and up to date: 
    pip install -U "owocr>=1.15"
  2. Start owocr with the correct parameters: 
    owocr -r websocket -w websocket -of json -e glens
  3. Verify owocr is running: 
    # 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)
owocr versions older than 1.15.0 do not support the websocket protocol required by meikipop.
Error message: Please download the screenai component...Cause: Screen AI library files are not installed.Solution:
1

Download Screen AI components

Visit Chrome’s infrastructure packages and download the appropriate version for your platform.
2

Extract to correct location

Extract the contents to:
  • Linux: ~/.config/screen_ai/resources/
  • Windows: %USERPROFILE%\.config\screen_ai\resources\
3

Verify files are present

Ensure chrome_screen_ai.dll (Windows) or libchromescreenai.so (Linux) is in the resources directory.
4

Restart meikipop

The provider will automatically initialize with the new components.
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: 
    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

​
Platform-specific issues

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: 
    [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
macOS support is experimental. If you encounter issues, please report them on GitHub to help improve compatibility.
Symptom: meikipop crashes or can’t capture screen.Cause: Required macOS permissions not granted.Solution:
1

Open System Preferences

Go to System Preferences → Security & Privacy → Privacy
2

Grant Input Monitoring permission

Add your terminal app (Terminal.app, iTerm, etc.) to Input Monitoring and enable it.
3

Grant Screen Recording permission

Add your terminal app to Screen Recording and enable it.
4

Grant Accessibility permission

Add your terminal app to Accessibility and enable it.
5

Restart terminal and meikipop

Close your terminal completely and reopen it, then start meikipop again.
Symptom: Screen capture not working on Linux.Cause: meikipop currently only supports X11, not Wayland.Solution:
  1. Check if you’re running Wayland: 
    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
Wayland support is planned but not yet implemented. X11 is currently required.
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: 
    python -m src.main
meikipop requires screen capture permissions which some antivirus software may flag. The official releases are safe.

​
Performance issues

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)
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: 
    [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

​
Configuration issues

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: 
    # 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
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: 
    [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

​
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
  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
Run meikipop from source (python -m src.main) to see detailed console output which can help diagnose issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us