1---
  2title: Troubleshooting
  3description: "Common issues and solutions for Zed on all platforms."
  4---
  5
  6# Troubleshooting
  7
  8This guide covers common troubleshooting techniques for Zed.
  9Sometimes you'll be able to identify and resolve issues on your own using this information.
 10Other times, troubleshooting means gathering the right information (logs, profiles, or reproduction steps) to help us diagnose and fix the problem.
 11
 12> **Note**: To open the command palette, use `cmd-shift-p` on macOS or `ctrl-shift-p` on Windows / Linux.
 13
 14## Retrieve Zed and System Information
 15
 16When reporting issues or seeking help, it's useful to know your Zed version and system specifications. You can retrieve this information using the following actions from the command palette:
 17
 18- {#action zed::About}: Find your Zed version number
 19- {#action zed::CopySystemSpecsIntoClipboard}: Populate your clipboard with Zed version number, operating system version, and hardware specs
 20
 21## Zed Log
 22
 23Often, a good first place to look when troubleshooting any issue in Zed is the Zed log, which might contain clues about what's going wrong.
 24You can review the most recent 1000 lines of the log by running the {#action zed::OpenLog} action from the command palette.
 25If you want to view the full file, you can reveal it in your operating system's native file manager via {#action zed::RevealLogInFileManager} from the command palette.
 26
 27You'll find the Zed log in the respective location on each operating system:
 28
 29- macOS: `~/Library/Logs/Zed/Zed.log`
 30- Windows: `C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
 31- Linux: `~/.local/share/zed/logs/Zed.log` or `$XDG_DATA_HOME`
 32
 33> **Note:** In some cases, it might be useful to monitor the log live, such as when [developing a Zed extension](https://zed.dev/docs/extensions/developing-extensions).
 34> Example: `tail -f ~/Library/Logs/Zed/Zed.log`
 35
 36The log may contain enough context to help you debug the issue yourself, or you may find specific errors that are useful when filing a [GitHub issue](https://github.com/zed-industries/zed/issues/new/choose) or when talking to Zed staff in our [Discord server](https://zed.dev/community-links#forums-and-discussions).
 37
 38## Performance Issues (Profiling)
 39
 40If you're running into performance issues in Zed (hitches, hangs, or general unresponsiveness), having a performance profile attached to your issue will help us zero in on what is getting stuck.
 41
 42### macOS
 43
 44Xcode Instruments (which comes bundled with your [Xcode](https://apps.apple.com/us/app/xcode/id497799835) download) is the standard tool for profiling on macOS.
 45
 461. With Zed running, open Instruments
 471. Select `Time Profiler` as the profiling template
 481. In the `Time Profiler` configuration, set the target to the running Zed process
 491. Start recording
 501. If the performance issue occurs when performing a specific action in Zed, perform that action now
 511. Stop recording
 521. Save the trace file
 531. Compress the trace file into a zip archive
 541. File a [GitHub issue](https://github.com/zed-industries/zed/issues/new/choose) with the trace zip attached
 55
 56<!--### Windows-->
 57
 58<!--### Linux-->
 59
 60## Startup and Workspace Issues
 61
 62Zed creates local SQLite databases to persist data relating to its workspace and your projects. These databases store, for instance, the tabs and panes you have open in a project, the scroll position of each open file, the list of all projects you've opened (for the recent projects modal picker), etc. You can find and explore these databases in the following locations:
 63
 64- macOS: `~/Library/Application Support/Zed/db`
 65- Linux and FreeBSD: `~/.local/share/zed/db` (or within `XDG_DATA_HOME` or `FLATPAK_XDG_DATA_HOME`)
 66- Windows: `%LOCALAPPDATA%\Zed\db`
 67
 68The naming convention of these databases takes on the form of `0-<zed_channel>`:
 69
 70- Stable: `0-stable`
 71- Preview: `0-preview`
 72- Nightly: `0-nightly`
 73- Dev: `0-dev`
 74
 75While rare, we've seen a few cases where workspace databases became corrupted, which prevented Zed from starting.
 76If you're experiencing startup issues, you can test whether it's workspace-related by temporarily moving the database from its location, then trying to start Zed again.
 77
 78> **Note**: Moving the workspace database will cause Zed to create a fresh one.
 79> Your recent projects, open tabs, etc. will be reset to "factory".
 80
 81If your issue persists after regenerating the database, please [file an issue](https://github.com/zed-industries/zed/issues/new/choose).
 82
 83## Language Server Issues
 84
 85If you're experiencing language-server related issues, such as stale diagnostics or issues jumping to definitions, restarting the language server via {#action editor::RestartLanguageServer} from the command palette will often resolve the issue.
 86
 87## Agent Error Messages
 88
 89### "Max tokens reached"
 90
 91> **Preview:** This error handling is available in Zed Preview. It will be included in the next Stable release.
 92
 93You see this error when the agent's response exceeds the model's maximum token limit. This happens when:
 94
 95- The agent generates an extremely long response
 96- The conversation context plus the response exceeds the model's capacity
 97- Tool outputs are large and consume the available token budget
 98
 99**To resolve this:**
100
1011. Start a new thread to reduce context size
1022. Use a model with a larger token limit in AI settings
1033. Break your request into smaller, focused tasks
1044. Clear tool outputs or previous messages using the thread controls
105
106The token limit varies by model—check your model provider's documentation for specific limits.