Troubleshooting

Fresh

Common issues and solutions for Warp Terminal and the Oz Platform.

Installation Issues

Warp won't install on macOS

Symptom	Solution
"App is damaged" warning	Run `xattr -cr /Applications/Warp.app` in default Terminal
Installer hangs	Check macOS version (requires 12+), restart and retry
Homebrew install fails	Run `brew update && brew install --cask warp`

Warp won't install on Windows

Symptom	Solution
Installer doesn't launch	Run as Administrator
Missing Visual C++ runtime	Install Visual C++ Redistributable
Windows version not supported	Requires Windows 10 build 19041+ or Windows 11

Warp won't install on Linux

Symptom	Solution
Package not found	Add Warp repository first, then install
GPU rendering issues	Try `LIBGL_ALWAYS_SOFTWARE=1 warp-terminal`
Wayland issues	Set `WARP_ENABLE_WAYLAND=1` or fall back to X11

Authentication Issues

WARNING

Warp requires an account for full functionality.

Symptom	Solution
OAuth popup blocked	Allow popups for `app.warp.dev`
SSO not working	Contact your team admin to verify SSO configuration
API key auth fails	Regenerate key at `app.warp.dev` > Settings > API Keys
"Session expired"	Sign out and sign back in

Agent Issues

Agent not responding

Agent makes wrong changes

Issue	Solution
Agent edits wrong files	Add project rules in `AGENTS.md` specifying file boundaries
Agent uses wrong framework	Add technology stack to `AGENTS.md` rules
Agent ignores conventions	Define coding standards explicitly in rules
Agent runs dangerous commands	Set approval profile to require confirmation

Cloud agent fails

Symptom	Solution
"Environment not found"	Verify environment ID in Oz web app
"Insufficient credits"	Check credit balance (cloud runs need 20+ credits)
Agent times out	Break task into smaller skills
Wrong repo checked out	Verify repo link in environment settings
Secrets not available	Re-add secrets in environment configuration

Skills Issues

Skill not loading

Symptom	Solution
`/skill-name` not recognized	Verify file is at `.agents/skills/skill-name/SKILL.md`
Skill in wrong scope	Project skills: `.agents/skills/`, Global: `~/.warp/agents/skills/`
YAML frontmatter error	Check for valid `name` and `description` fields
Name conflict	Project skills override global skills with the same name

Skill not behaving as expected

Ensure skill instructions are specific and unambiguous
Add example inputs/outputs to the skill file
Test with oz agent run --skill "path:skill-name" locally first
Check that supporting files referenced in the skill exist

MCP Server Issues

MCP server won't connect

Symptom	Solution
"Server not found"	Run `oz mcp list` to verify server is registered
Connection timeout	Check that the MCP server process is running
Authentication error	Verify credentials in MCP server configuration
Tools not available	Restart Warp after adding a new MCP server

MCP server in cloud agents

INFO

MCP servers used in cloud agents must have their environment variables configured in the cloud environment settings.

Performance Issues

Warp is slow

Symptom	Solution
Slow rendering	Check GPU drivers are up to date
High CPU usage	Close unused tabs and panes
Slow autocomplete	Disable AI completions if not needed
Large output lag	Use `less` or `head` for large command outputs

Terminal output issues

Symptom	Solution
Garbled output	Reset terminal: `reset` or `tput reset`
Colors not showing	Check `TERM` is set to `xterm-256color`
Unicode not rendering	Install a Nerd Font or use Warp's built-in fonts

Symptom	Solution
Share link not generated	Ensure you're signed in and on a team plan
Collaborator can't join	Verify their email matches the share target
Edit access not working	Use `--share user@email:edit` (include `:edit` suffix)
Team share fails	Verify team membership in Settings > Teams

Common Error Messages

Error	Meaning	Fix
`EACCES permission denied`	File permission issue	Check file ownership and permissions
`command not found: oz`	Oz CLI not installed or not in PATH	Run installer or add to PATH
`rate_limit_exceeded`	Too many API requests	Wait 60 seconds and retry
`invalid_api_key`	API key is wrong or expired	Regenerate at app.warp.dev
`model_not_available`	Selected model not accessible	Switch to a different model
`environment_not_configured`	Cloud environment missing	Set up environment in Oz web app

Getting Help

In-app: Use the ? icon or Command Palette
Documentation: docs.warp.dev
Community: Warp Discord
Support: support@warp.dev

See Also