Common Issues

This page covers the most frequently reported issues grouped by feature area. For permission and accessibility problems, see Permissions & Accessibility.

Startup & General#

IrukaDark doesn't launch / shows a blank window#

1. Quit completely and relaunch — Press Cmd+Q (macOS) or close from the system tray (Windows), then start the app again.
2. Check for another running instance — IrukaDark enforces a single instance. If a background process is stuck, use Activity Monitor (macOS) or Task Manager (Windows) to force-quit any IrukaDark process, then relaunch.
3. Reset preferences — A corrupted settings file can prevent startup. Delete the preferences file and relaunch:
   • macOS: ~/Library/Application Support/irukadark/irukadark.prefs.json
   • Windows: %APPDATA%\IrukaDark\irukadark.prefs.json

App feels slow or uses too much memory#

IrukaDark allocates up to 2 GB of memory for processing large datasets. If the app is consuming excessive resources:

1. Restart IrukaDark to clear accumulated state
2. If clipboard history is large (1000+ items), consider clearing old entries
3. Close the chat window when not in use — active conversations maintain context in memory

App doesn't start at login#

IrukaDark supports auto-start on login. If it's not starting:

• macOS: Go to IrukaDark Settings and ensure Start at Login is enabled. If already enabled, toggle it off and on again.
• Windows: Check Settings → Apps → Startup and confirm IrukaDark is listed and enabled.

AI Features#

"Insufficient credits"#

This error (HTTP 402) means your credit balance is zero.

• Check your current balance in Dashboard → Credits
• Free plan users receive a monthly credit allowance that resets each billing cycle
• Team plan Owners can purchase additional credit packs from the Credits page
• Upgrade your plan for a higher monthly allowance

AI response is empty or cut off#

1. Check your internet connection — IrukaDark requires an active connection for all AI features
2. Try again — Temporary API issues can cause incomplete responses. Wait a few seconds and retry.
3. Simplify your request — Very long text selections or complex prompts may hit processing limits. Try selecting a smaller portion of text.

"Rate limit exceeded. Please wait X seconds."#

You've sent too many requests in a short period. Wait the indicated number of seconds (usually 60) before trying again. This limit protects the service from overload and applies per-account.

"Unexpected response from API"#

A server-side issue. Usually resolves on its own within a few minutes. If it persists:

1. Check your internet connection
2. Restart IrukaDark
3. If the issue continues for more than 30 minutes, check the IrukaDark status page for service announcements

"Authentication required"#

Your session has expired.

1. Sign out from IrukaDark Settings
2. Sign in again
3. If the issue persists, restart the app and sign in again

Screenshot Explain#

Screenshot captures a black or blank image#

• macOS: The Screen Recording permission is likely missing. See Permissions → Screen Recording.
• Windows: Some apps use hardware-accelerated rendering that can block screen capture:
  1. In the target app, disable Hardware Acceleration in its settings (e.g., Chrome: Settings → System → Use hardware acceleration)
  2. Update your graphics driver to the latest version
  3. On Windows 11 24H2+, check Settings → Privacy & security → Screen capture

Screenshot Explain returns nothing#

1. Ensure you selected a visible region — minimized or fully obscured windows may produce unusable captures
2. Check your credits balance — Screenshot Explain consumes credits for each analysis
3. Try a smaller or more focused selection area

Crosshair cursor doesn't appear#

The Screen Recording permission may not be granted, or the app needs a restart after granting it.

• macOS: Grant Screen Recording in System Settings, then restart IrukaDark (Cmd+Q and relaunch)
• Windows: Restart IrukaDark

Text Explain & Translate#

Text Explain does nothing when triggered#

• macOS: The Accessibility permission is required to read selected text. See Permissions → Accessibility.
• All platforms: Ensure text is actually selected before pressing the shortcut. Some apps (e.g., terminal emulators, remote desktop clients) may not expose text selection to the OS.

Translate & Replace doesn't replace the text#

This feature requires both:

1. Accessibility permission (macOS) — to read the selected text and simulate keyboard input
2. Automation permission (macOS) — to paste into the target app

If the translated text appears in the IrukaDark popup but doesn't replace the original:

• Check System Settings → Privacy & Security → Automation and ensure the target app is listed under IrukaDark
• Some apps block programmatic paste. Try using Cmd+V manually after the translation appears in the popup.

Wrong language detected or translated#

IrukaDark auto-detects the source language. To improve accuracy:

1. Select a longer passage of text (short fragments can be ambiguous)
2. Set your preferred target language in IrukaDark's Settings → Language
3. Use the /translate_ja, /translate_en, etc. slash commands in AI Chat for explicit language targeting

AI Notetaker#

"Failed to start recording"#

1. Check permissions — Both Screen Recording and Microphone permissions are needed. See Permissions.
2. Check if another recording is active — Only one recording session can run at a time. Stop any existing recording first.
3. Restart IrukaDark — A stale recording state can sometimes persist. Quit and relaunch the app.

"Screen recording permission required for system audio"#

System audio capture requires the Screen Recording permission on macOS. Even if you only want to record microphone audio, this permission is needed for the full recording pipeline.

Follow Permissions → Screen Recording and restart IrukaDark after granting the permission.

"Microphone permission denied"#

• macOS: See Permissions → Microphone
• Windows: Go to Settings → Privacy & security → Microphone and ensure both the global toggle and the "Let desktop apps access your microphone" toggle are on

No system audio is captured (only microphone works)#

On macOS, system audio capture requires Screen Recording permission. If microphone works but system audio is silent:

1. Verify Screen Recording is enabled for IrukaDark
2. Restart IrukaDark after granting the permission
3. Ensure the meeting app is outputting audio to the same audio device IrukaDark is monitoring

Recording is silent or very quiet#

1. Check microphone input level — The audio level indicator in the Notetaker UI should show activity when you speak. If it's flat, your microphone may not be selected correctly.
2. Select the correct audio source — In the Notetaker UI, verify the correct microphone and system audio source are selected.
3. Check system volume — Ensure your system audio output is not muted.

"Failed to load recording" / Video preview doesn't play#

The recording file may be corrupted or incomplete (e.g., if the app crashed during recording).

1. Check that the recording file exists in the app's recordings directory
2. Try exporting the recording — even if preview fails, the export may still work
3. If the file is corrupted, the recording cannot be recovered

Export fails#

Transcription quality is poor#

1. Add custom terms — Go to the Notetaker dictionary and add specialized vocabulary, product names, and technical terms (up to 100 terms)
2. Improve audio quality — Use a dedicated microphone instead of a laptop mic. Reduce background noise.
3. Check language settings — Ensure the transcription language matches the meeting language

Clipboard & Snippets#

Clipboard History Popup doesn't open#

1. Check the shortcut — Default is Cmd+Shift+V (macOS) or Alt+V (Windows). Verify in IrukaDark Settings → Shortcuts.
2. Check for conflicts — Other clipboard managers (e.g., Paste, CopyClip, Ditto) may claim the same shortcut. Disable or remap them.
3. Restart IrukaDark — The clipboard monitor may need reinitialization.

Clipboard items are missing or not saved#

IrukaDark stores up to 1000 text items and 30 images. Older items are automatically removed when the limit is reached. Clipboard monitoring starts when the app launches — items copied before IrukaDark was running are not captured.

Paste doesn't work from Clipboard History#

• macOS: Accessibility permission is required for paste simulation. See Permissions → Accessibility.
• Some apps intercept or block programmatic paste. Try Cmd+V / Ctrl+V manually after selecting an item.

Snippet import fails#

Keyboard Shortcuts#

Shortcuts don't work at all#

1. Check if shortcuts are disabled — Look for the "Disable all shortcuts" toggle in Settings
2. macOS: Grant Accessibility permission — this is required for global shortcut registration
3. Restart IrukaDark — Shortcuts are registered on startup; a restart can resolve stale registrations
4. Check for conflicts — Another app may have claimed the same shortcuts. Common culprits: screen recorders, clipboard managers, window managers, IDE global shortcuts

"Failed to register shortcut. There may be a conflict with another app."#

Another application has already registered the same global shortcut. To resolve:

1. Identify the conflicting app (try closing apps one by one to find it)
2. Either remap the shortcut in IrukaDark Settings, or change the conflicting app's shortcut

"This shortcut is reserved by the system"#

Certain key combinations are reserved by the OS and cannot be used. Choose a different shortcut combination.

Shortcuts stop working after sleep/wake (macOS)#

macOS can occasionally deregister global shortcuts after the system wakes from sleep.

• Restart IrukaDark to re-register all shortcuts
• If this happens frequently, check for macOS updates that may fix the issue

Shortcuts don't work with non-US keyboard layout#

IrukaDark registers shortcuts based on key codes, which may not match the label printed on non-US keyboards. Open IrukaDark Settings → Shortcuts and re-bind the shortcut by pressing the desired key combination on your keyboard.

Content Generation (Images, Videos, Slides)#

Image generation fails#

1. Check credits — Each generation request consumes credits
2. Simplify the prompt — Very complex prompts may fail. Try a shorter, clearer description.
3. Check aspect ratio — Use /image status to verify your current settings

Video generation times out#

Video generation can take several minutes. If it times out after 10 minutes:

1. Try a shorter duration (use /video duration 4 for a 4-second video)
2. Simplify the prompt
3. Check your internet connection — large video files require a stable connection for download

"Failed to generate slide" / "Please generate summary first"#

Slide generation requires an existing summary. Ensure you've generated a summary before requesting slides. If the summary already exists but slides still fail, try regenerating the summary first.

Template errors#

URL Summary#

"No valid URL detected"#

Ensure you've selected a complete HTTP or HTTPS URL. Partial URLs, file paths, and non-HTTP protocols are not supported. The URL must include http:// or https://.

Window Control (macOS)#

Window snap shortcuts don't work#

1. Check Accessibility permission — Window control requires Accessibility access
2. Check shortcut conflicts — Window management apps (Rectangle, Magnet, BetterSnapTool) often use Ctrl+Option+Arrow combinations. Disable or remap them.
3. Multi-monitor issues — If the window moves to an unexpected monitor, use Ctrl+Option+N / Ctrl+Option+P to navigate between monitors

Updates#

"Failed to check for updates"#

1. Check your internet connection — The update check requires access to dl.irukadark.com
2. Firewall/proxy — Ensure dl.irukadark.com is not blocked by your network's firewall or proxy
3. Try again later — The update server may be temporarily unavailable

Update downloaded but not installed#

After downloading an update, IrukaDark prompts you to restart. If you dismissed the prompt:

• macOS: Quit IrukaDark (Cmd+Q) and relaunch — the update will be applied on next startup
• Windows: Close and reopen IrukaDark — the Squirrel updater applies the update during restart

Network & Connectivity#

All AI features return errors#

If every AI feature fails simultaneously:

1. Check your internet connection — IrukaDark requires an active connection for AI features
2. Check your firewall/proxy — Ensure IrukaDark can reach its API servers. Allowlist the app in your firewall settings.
3. Corporate networks — Some corporate firewalls or proxies block unknown HTTPS traffic. Contact your IT department to allowlist IrukaDark.
4. VPN — If using a VPN, try disconnecting temporarily to test if it's the cause

Slow response times#

1. Check your internet speed — AI features require a stable connection. Streaming responses may stutter on very slow connections.
2. Try a simpler request — Long text selections or complex prompts take longer to process
3. Peak hours — Server response times may increase during peak usage periods