# Troubleshooting

> Available on: Mac, Windows, iOS

Steps to diagnose and fix common Raycast issues on Mac, Windows, and iOS, plus how to gather the right information before reaching out to the team.

If something isn't working as expected in Raycast, this page walks you through the steps you can take yourself, the diagnostic information that helps us pin down what's going wrong, and how to send it to the team.

The steps below cover Raycast for Mac, Windows, and iOS. Where the platforms differ, you'll see specific instructions for each. Working through this list before reaching out usually shortens the back-and-forth and gets you to a fix faster.

## Try these first

Most Raycast issues fall into a handful of common patterns. Before sending a report, run through these quick checks. They take a few minutes and resolve a large share of issues on their own.

<details>
<summary>Update Raycast to the latest version</summary>
<PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      In Raycast, search for `Check for Updates` and install any pending update.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      In Raycast, search for `Check for Updates`, or open the Microsoft Store, go to `Library`, and update Raycast from there. Microsoft sometimes takes a while to roll out updates regionally.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      Open the App Store on your device, tap your profile picture, scroll to `Available Updates`, and update Raycast. Several recent iOS bugs (AI Chat crashes, dictation glitches) were fixed in point releases, so updating alone often resolves the issue.
    </PlatformTabs.Content>
  </PlatformTabs.Root>

  Many issues are fixed within one or two releases of being reported. If yours has been around for a while, the latest version may already have the fix.
</details>

<details>
<summary>Check that Raycast has the right permissions</summary>
Several Raycast features rely on explicit OS permissions. If a feature stopped working after a system update, this is the first place to check.

  <PlatformTabs.Root platforms={["mac", "ios"]}>
    <PlatformTabs.Content platform="mac">
      - Open `System Settings → Privacy & Security`.
      - Confirm Raycast is enabled under `Accessibility` (needed for hotkeys and snippet expansion).
      - Confirm Raycast is enabled under `Screen Recording` (needed for window management).
      - If you use AI dictation, also check `Microphone`.
      - If Raycast appears in a list but the toggle looks off, toggle it off and on again.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      - To use the Raycast keyboard outside the app, open `Settings → General → Keyboard → Keyboards`, tap `Raycast`, and turn on `Allow Full Access`. Without it, AI Commands and dictation won't work from the keyboard.
      - For dictation, open `Settings → Raycast` and confirm `Microphone` is enabled.
      - If you're hitting login issues like "Token expired", check `Settings → General → Date & Time` and make sure `Set Automatically` is on. An incorrect clock blocks token validation.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>Make sure only one version of Raycast is running</summary>
- Open `Activity Monitor` and search for `Raycast`. If you see two processes, quit the one you don't want to use.
  - If you use both intentionally, make sure `Enable Snippet Expansion` is on in only one of them.
</details>

<details>
<summary>Check for conflicts with other tools</summary>
If a specific keyboard or text feature is misbehaving, another app on your device may be intercepting the same input. Common culprits:

  - **Text expansion tools** (TextExpander, aText, Espanso, PhraseExpress, macOS Text Replacements) competing with Raycast Snippets.
  - **Keyboard remapping tools** (Karabiner-Elements on Mac, AutoHotKey or Kanata on Windows, PowerToys Keyboard Manager, BetterTouchTool, Hammerspoon).
  - **Other launchers or hotkey apps** bound to the same shortcut (Spotlight, Alfred, LaunchBar on Mac; Windows Search, PowerToys Run, Flow Launcher on Windows).
  - **Antivirus or endpoint protection** on Windows occasionally quarantines parts of Raycast as `IDP.Generic` or similar. If features stop working suddenly, check your antivirus quarantine and add Raycast to the exclusion list.
  - **Other custom keyboards on iOS** can interfere with the Raycast keyboard's text replacements and dictation. If a feature suddenly stops working, switch to the default keyboard temporarily to see whether the issue follows.
  - Temporarily disabling the suspected tool helps confirm whether the conflict is real.
</details>

## Common situations

If the first-aid steps didn't help, see whether your issue matches one of the patterns below. Each one expands with steps specific to that situation.

<details>
<summary>Raycast won't open, or crashes immediately on launch</summary>
<PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      - Download the latest version from https://www.raycast.com/new and reinstall by dragging the new app into `Applications` (replace the existing one when prompted).
      - If reinstalling doesn't help, fully uninstall Raycast with AppCleaner, then install fresh.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      - Open the Microsoft Store, search for Raycast, and click `Update` if one is available.
      - If the install or update itself fails (for example with error `0x80073cf9`), repair the Microsoft App Runtime: `Settings → Apps → Installed apps`, search for `Microsoft Windows App Runtime Singleton`, open `Advanced options`, click `Terminate`, then `Repair`, then `Reset` if Repair fails. Install Raycast again.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      - Update iOS to the latest version. Several reports of "app won't open" on iOS resolved after a system update.
      - Delete the Raycast app and reinstall it from the App Store. This clears local state that can cause launch crashes.
      - If reinstalling doesn't help, grab the iOS crash log so we can investigate. See `A crash report` in the section below.
    </PlatformTabs.Content>
  </PlatformTabs.Root>

  If Raycast still won't launch after a reinstall on any platform, see `A crash report` in the section below.
</details>

<details>
<summary>Raycast is unresponsive, frozen, or stuck on a loading screen</summary>
- Quit Raycast (or force quit if needed) and reopen.
  - If the freeze comes back immediately, restart your device.
  - If the freeze happens in a specific situation (opening a particular extension, switching tabs in a specific view, typing a specific query, opening a specific AI Chat), note exactly what triggers it. Steps to reproduce are the single most useful piece of information you can give us.

  <PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      Run `Copy Raycast Logs` before doing anything else.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      Run `Copy Raycast Logs` before doing anything else.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      Enable Engineering Mode and export logs (see `Raycast logs` below).
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>Raycast doesn't open at login / startup</summary>
<PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      - Open `System Settings → General → Login Items & Extensions` and confirm Raycast is in the `Open at Login` list and enabled.
      - If it's already enabled but doesn't fire, remove it and re-add it. The macOS login-items database occasionally gets stuck.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      - Open `Raycast Settings → General` and confirm `Open at Login` is enabled. On Windows, Raycast manages startup through Task Scheduler under the hood, so this setting is the source of truth (rather than `Startup Apps` in Task Manager).
      - If you've enabled it but it still doesn't fire, update to the latest Raycast version. A series of fixes for autostart on Windows shipped in 0.56.2 and later.
      - If a brief PowerShell or terminal window flashes during login, that's the Raycast startup launcher and is harmless.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      Not applicable. The iOS app is launched on demand from the Home Screen, App Library, Spotlight, or via the Raycast keyboard from within other apps.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>The Raycast keyboard doesn't work in other apps</summary>
<Platform platform="ios" />

  - Open `Settings → General → Keyboard → Keyboards`, tap `Raycast`, and turn on `Allow Full Access`. Without it, dictation, AI Commands, and clipboard-based features can't run.
  - If commands aren't showing up on the keyboard, delete and reinstall the Raycast iOS app. Some users have resolved missing commands this way.
  - If the keyboard appears but seems to crash or freeze a third-party app (for example Microsoft Word or Excel), check whether the same crash happens with the default iOS keyboard. Some app-side bugs are unrelated to Raycast even when the timing makes it look like the keyboard is the cause.
</details>

<details>
<summary>A keyboard shortcut doesn't fire</summary>
- Open `Raycast Settings > Shortcuts` and confirm the hotkey is still assigned. System updates occasionally clear hotkeys.
  - Make sure another app isn't holding the same shortcut. If you suspect a conflict, temporarily disable the other app and try again.

  <PlatformTabs.Root platforms={["mac", "windows"]}>
    <PlatformTabs.Content platform="mac">
      - Open `System Settings → Privacy & Security → Accessibility` and confirm Raycast is enabled. Without it, no Raycast hotkey can register.
      - If your hotkey is set through Karabiner-Elements or similar, that tool may take a few seconds to activate after your Mac wakes from sleep.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      - Some shortcuts are reserved by Windows. `Ctrl+Esc` opens the Start menu, so the default `Pop to Root` binding is disabled on Windows. Other `Esc` combinations and various `Win+...` shortcuts are also reserved. Pick a combination that isn't claimed by Windows.
      - If you use a non-US keyboard layout, watch for `Alt` combinations that conflict with `AltGr` characters. In the Raycast hotkey recorder, you can choose between a key-equivalent binding and a layout-independent binding.
      - If your hotkey is configured through AutoHotKey, Kanata, or PowerToys Keyboard Manager, try disabling that tool and binding the hotkey directly inside Raycast as a test.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>Snippets aren't expanding when I type the keyword</summary>
- Check that `Enable Snippet Expansion` is on in `Raycast Settings → Snippets`.
  - As a quick reset, toggle `Enable Snippet Expansion` off, wait a moment, then turn it back on.
  - Make sure your keyword doesn't contain spaces, quotes, or backticks. Those act as delimiters and prevent the keyword from matching.
  - Some apps with custom text input (certain code editors, terminals, password managers) don't support text replacement. Try the snippet inside another app to confirm the issue is broader, or run `Search Snippets` and paste manually.

  <Platform platform="mac" /> Verify Raycast has Accessibility permission in `System Settings → Privacy & Security → Accessibility`.
</details>

<details>
<summary>Raycast is using a lot of memory</summary>
- Check the OS task viewer (Activity Monitor on Mac, Task Manager on Windows) to confirm the figure. Some third-party stats tools report inflated numbers.
  - Quit and reopen Raycast. Memory should drop noticeably once it restarts.
  - If you have very large file collections indexed, Raycast's file index can grow large. Add big or rarely-used folders to `Raycast Settings → File Search → Ignore Patterns` to keep the index smaller.
  - If memory grows continuously over hours of use, that's a leak we want to know about. The steps below help us collect the data we need to investigate.

  <PlatformTabs.Root platforms={["mac", "windows"]}>
    <PlatformTabs.Content platform="mac">
      1. Quit Raycast fully via the menu bar icon or the `Quit Raycast` command, and wait a few seconds for it to disappear from Activity Monitor.
      2. Clear existing logs: in Finder, press `⌘⇧G`, paste `~/Library/Logs/com.raycast.macos` (or `~/Library/Logs/com.raycast-x.macos` for Beta), and move the folder's contents to the Trash.
      3. Relaunch Raycast and use it the way you normally do. Don't try to "force" the issue.
      4. When you see a spike: note the exact time (with time zone), optionally screenshot Activity Monitor with Raycast expanded to show each subprocess, then run `Copy Raycast Logs`.
      5. Send us the log files (from your clipboard) along with the time of the spike and any extra context (what you were doing right before).
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      1. Quit Raycast completely: right-click the system-tray icon → `Quit`, or use the `Quit Raycast` command.
      2. Wait a few seconds for it to disappear from the system tray / Task Manager.
      3. Clear existing logs: open File Explorer, paste `%LocalAppData%\Raycast` into the address bar, and delete the `Logs` folder.
      4. Launch Raycast in Diagnostic Mode: open the Start menu, search for `Raycast`, and in the right-hand panel click `Diagnostic Mode`. This enables more verbose logging.
      5. Use your computer as usual. Don't force the issue.
      6. When you see a spike: note the exact time (with time zone), optionally screenshot Task Manager with Raycast expanded to show each subprocess, then run `Copy Raycast Logs`.
      7. Send us the log files (from your clipboard) along with the time of the spike and any extra context (what you were doing right before).

      Important: Raycast stays in `Diagnostic Mode` until you fully quit it. Diagnostic Mode is not persistent across reboots. After restarting your computer, Raycast starts in normal mode again unless you explicitly use Diagnostic Mode.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>File Search is slow, missing files, or stuck indexing</summary>
- Open `Raycast Settings → File Search` and confirm the folders you expect are listed under `Search Scopes`.
  - If indexing hangs on a very large folder, exclude it through `Ignore Patterns`.

  <PlatformTabs.Root platforms={["mac", "windows"]}>
    <PlatformTabs.Content platform="mac">
      Encrypted cloud-storage folders (for example Google Drive's `.Encrypted` folder) are a known hang point. Add these patterns to `Ignore Patterns`: `**/Library/CloudStorage/**/.Encrypted`, `**/Library/CloudStorage/**/.Encrypted/`, `**/Library/CloudStorage/**/.shortcut-targets-by-id`, `/Library/CloudStorage/**/.shortcut-targets-by-id/**`
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      Exclude network drives, virtual machine images, and large `node_modules` trees if you're indexing developer folders. Use the same `Ignore Patterns` field.
    </PlatformTabs.Content>
  </PlatformTabs.Root>

  Quit and reopen Raycast so indexing restarts.
</details>

<details>
<summary>An extension crashes or behaves unexpectedly</summary>
- Try reloading the extension: in Raycast, search for the affected extension and run any of its commands again. Many transient failures clear on a re-run.
  - Update the extension to the latest version from the Raycast Store (`Search Store` in Raycast).
  - If the issue is reproducible, include the extension name and version (visible on its Store page) in your report.
  - For locally developed extensions, make sure `@raycast/api` in your `package.json` is up to date and run `npm install` before `npm run dev` again. As a quick way to use the latest CLI without changing your `package.json`, run `npx @raycast/api@latest dev`.
</details>

<details>
<summary>Antivirus quarantined Raycast</summary>
<Platform platform="windows" />

  Some Windows antivirus tools occasionally flag Raycast as suspicious because it monitors clipboard contents and keystrokes, both of which are core to the launcher. The most common false positive is Norton's behavioural detection reporting `IDP.Generic`.

  - Open your antivirus dashboard, find Raycast in the quarantine list, and restore it.
  - Add Raycast to your antivirus exclusion / allow list so the same files aren't quarantined again.
  - If the antivirus also deleted Raycast's startup task, you may need to reinstall from the Microsoft Store to re-create it.
</details>

## Information to gather before reporting

When you do reach out, the more concrete information you can include, the faster we can reproduce and fix the issue. Most reports benefit from including each of the items below.

<details>
<summary>Your Raycast version and OS version</summary>
<PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      Raycast version: open `Raycast Settings → About`. macOS version: `System Settings → General → About` (for example `15.4`).
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      Raycast version: open `Raycast Settings → About`. Windows version: `Settings → System → About`. Note the edition (e.g. `Windows 11 Pro`), version (e.g. `24H2`), build (e.g. `26100.x`), and architecture (`x64` or `ARM64`).
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      Raycast version: open the Raycast app, tap your account avatar, then `Settings → About`. The version is also included automatically when you use `Share Feedback` from the iOS app. iOS version and device: `Settings → General → About`. Note both the iOS version (e.g. `26.4.1`) and the device model (e.g. `iPhone 18,1`).
    </PlatformTabs.Content>
  </PlatformTabs.Root>

  If you're using a beta version of Raycast or your OS, please call that out.
</details>

<details>
<summary>Steps to reproduce the issue</summary>
This is the single most valuable piece of information you can send. We can fix something we can see happen; something we can't reproduce often stays open.

  - Write down the exact sequence: which command you opened, which keys you pressed, which option you selected, what was different about your state (network offline, multiple monitors connected, specific app in focus, etc.).
  - Include whether it happens every time or only sometimes.
  - If the issue only happens in a specific app or text field, name that app.
</details>

<details>
<summary>Raycast logs</summary>
Raycast logs include enough detail for us to trace what happened internally without exposing personal data. They're small text files and easy to attach to a report.

  <PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      - In Raycast, search for `Copy Raycast Logs` to copy the latest log file to your clipboard, or `Reveal Raycast Logs` to open the log folder in Finder.
      - If Raycast won't launch at all, open Finder, press `⌘⇧G`, and paste `~/Library/Logs/com.raycast.macos` (or `~/Library/Logs/com.raycast-x.macos` if you use the Raycast Beta).
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      - In Raycast, search for `Copy Raycast Logs` or `Reveal Raycast Logs`.
      - If Raycast won't launch, open File Explorer and paste `%LOCALAPPDATA%\Raycast\logs` into the address bar. Sort by date modified and grab the most recent files.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      iOS log collection happens through Raycast's Engineering Mode. To enable it:

      1. Open Safari and visit `raycast://engineering-mode-321`. When prompted, allow the link to open in the Raycast app.
      2. Open Raycast, go to `Settings`, and you'll see a new `Engineering Mode` entry. Tap into it.
      3. Reproduce the issue, then return to `Settings → Engineering Mode` and tap `Export Logs`. Share the exported file with your report.

      While you're in Engineering Mode, also tap `Copy Anonymous ID` and paste the value into your report. This lets us look up any crash signatures we've received from your device.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>A screen recording</summary>
A short recording is often clearer than any written description, especially for visual glitches or anything time-sensitive.

  For Mac and Windows, the quickest way is [ray.so/v2-record](https://ray.so/v2-record). Open the link in your browser, click record, capture what's happening, and share the resulting link in your report. No install needed.

  If you'd rather use a built-in tool:

  <PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      Press `⌘⇧5` to open macOS's built-in screen recording controls. Choose `Record Selected Portion` to capture just the Raycast window, or `Record Entire Screen` if context outside Raycast matters.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      Press `Win+Alt+R` to start a recording with the Xbox Game Bar, or open the `Snipping Tool` and use its built-in screen recorder.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      - Add the `Screen Recording` control to Control Center: `Settings → Control Center` → tap `+` next to `Screen Recording`.
      - Open Control Center and tap the record button. Reproduce the issue, then stop the recording from the red status bar at the top of the screen. The video saves to your Photos library; attach it to your report.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

<details>
<summary>A crash report</summary>
If Raycast quits unexpectedly, your operating system generates a crash report you can send us. This contains the stack trace at the moment of failure, which is by far the most useful information for diagnosing launch and crash bugs.

  <PlatformTabs.Root platforms={["mac", "windows", "ios"]}>
    <PlatformTabs.Content platform="mac">
      - Open `Console.app` (from `Applications → Utilities`, or search for it in Raycast).
      - In the sidebar, select `Crash Reports`. Find the most recent entry with `Raycast` in the name, click it, then use `File → Save As` or right-click → `Reveal in Finder`.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="windows">
      - Open `Event Viewer` from the Start menu.
      - In the sidebar, expand `Windows Logs` and select `Application`.
      - Look for entries with `Source` of `Application Error` or `.NET Runtime` that mention `Raycast.exe` around the time of the crash.
      - Right-click each relevant entry, choose `Copy → Copy Details as Text`, and paste it into your report. Include the faulting module, exception code, and any stack frames you see.
    </PlatformTabs.Content>
    <PlatformTabs.Content platform="ios">
      - Open `Settings → Privacy & Security → Analytics & Improvements → Analytics Data`.
      - Scroll to find entries that start with `Raycast` and look at the date and time to match the crash. Tap one to view it.
      - Use the share button at the top right to send the file to yourself (Mail, AirDrop, etc.), then attach the file to your report. Pairing the crash report with the Anonymous ID from Engineering Mode is the most useful combination for iOS crashes.
    </PlatformTabs.Content>
  </PlatformTabs.Root>
</details>

Once you've gathered the information above, send it to us using the `Send Feedback` command inside Raycast (Mac and Windows) or the `Share Feedback` option inside the iOS app, or use one of the other channels listed on the [Contact Support](/contact-support) page.


---

## Need Help?

Contact Raycast Support if you have any questions or would like help with Troubleshooting. Use the **Send Feedback** command directly in Raycast to report bugs and billing issues, log feature requests, or any other queries you would like to speak to us about.

You can view all Raycast Support contact options at https://manual.raycast.com/contact-support