← All docs

Troubleshooting

Solutions for the most common issues. Work through the relevant section top to bottom — most problems are solved in the first or second step.

Red dot — "Not connected"

The connection dot in the Claunity header is red. The desktop app is not reachable.

1. Check if the desktop app is running

  • Windows — look for the Claunity icon in the system tray (bottom-right)
  • macOS — look for the Claunity icon in the menu bar (top-right)
  • Linux — check if the process is running: pgrep -a ClaunityApp

If it's not running — go back to the Claunity panel welcome screen and click ▶ Start Claunity.

2. Check the port

Claunity uses port 8765. If another application is using that port, the backend cannot start. Check what's on the port: 

# Windows (PowerShell)
netstat -ano | findstr :8765

# macOS / Linux
lsof -i :8765

If something else is on port 8765, close it and restart the Claunity app.

3. Restart the desktop app

Right-click the tray icon → Quit, then relaunch from the Claunity panel or by running the app directly. On Linux: killall ClaunityApp && ./ClaunityApp &

4. Firewall or antivirus blocking localhost

Some antivirus tools block local HTTP connections. Add an exception for ClaunityApp.exe (Windows) or ClaunityApp (macOS/Linux). The app only communicates on localhost:8765 — it makes no external connections except to AI provider APIs.

API key errors

"Invalid API key"

  • Make sure you copied the key correctly — no leading/trailing spaces
  • Check the key is active in your provider's dashboard
  • For Anthropic: console.anthropic.com → API Keys

"Access denied" / "Forbidden"

Your API key exists but doesn't have access to the selected model. This usually means your account needs a higher tier. Try switching to a smaller model (e.g. claude-haiku-4-5) to verify the key works, then upgrade your account for access to larger models.

"Rate limit hit"

You've sent too many requests too quickly. Claunity shows a retry button — wait a few seconds and try again. If this happens often, consider switching to a provider with higher rate limits or upgrading your API tier.

Claude Code mode not working

"Claude Code not found"

  • Install Claude Code: npm install -g @anthropic-ai/claude-code
  • Verify it's installed: claude --version
  • If the command works in terminal but not in Claunity, the binary may not be in the PATH seen by the desktop app. Restart the Claunity app after installing.

"Claude Code timed out"

Claude Code subprocess has a 120-second timeout. This can happen with very long prompts or slow network conditions. Try a shorter or simpler request. If it keeps timing out, switch to API Key mode.

Script compilation errors after Claunity edits

Claunity wrote code that doesn't compile

  • Copy the exact error from the Unity Console
  • Send it to Claunity: "Fix this compile error: [paste error]"
  • Claunity reads the file and fixes it

Domain reload loops

If Unity gets stuck in a compile loop after a script edit, close and reopen the project. Claunity's Smart Build state is saved in EditorPrefs and will resume correctly.

Script was partially written

If the AI was cut off mid-response (e.g. due to a network error), the script file may be incomplete. Ask Claunity to read and fix it: 

@ScriptName the file seems incomplete, please check and fix it

Actions not executing

Action preview appears but Apply does nothing

  • Make sure the scene is not in Play Mode — most actions require Edit Mode
  • Check the Unity Console for errors that may have locked the Editor
  • If there are compile errors, fix them first — Unity won't execute Editor scripts while compilation is failing

GameObject not found

Claunity uses the exact name of the GameObject as it appears in the Hierarchy. Names are case-sensitive. If the action fails with "object not found", check the name: 

What are the exact names of the objects in the scene?

Component not recognized

When adding or modifying components, use the exact C# class name. For example: Rigidbody not "rigid body", BoxCollider not "box collider". Claunity handles common variations, but exact names always work best.

Project Mode issues

Document upload fails

  • Supported formats: PDF, MD, TXT
  • Maximum recommended size: ~100KB of text content
  • For large PDFs, try copying the relevant sections into a .txt file instead

Plan generation takes too long

Large documents with detailed content can take 20–30 seconds to process. This is normal — the AI is reading the full document before responding. If it times out, try a shorter document or summarize the key points first.

Tasks keep failing during execution

If multiple tasks fail in a row, pause execution and switch to Vibe Mode to investigate. Ask Claunity what the current state of the project is and what went wrong: 

What is the current state of the project and what errors are in the console?

Auto-update issues

Update badge appears but update fails

  • Check your internet connection
  • On macOS, check that Claunity has permission to write to its install directory
  • If it keeps failing, download the latest version manually from the releases page and install it

App shows old version after update

The desktop app restarts automatically after an update. If the version hasn't changed, the app may not have fully restarted. Quit it from the tray and relaunch manually.

Still stuck?

If none of the above solved your problem, email us at support@claunity.com with:

  • Your OS and Unity version
  • Which AI provider and model you're using
  • The exact error message from the Claunity panel or Unity Console
  • Steps to reproduce the issue

We'll get back to you as soon as possible.

← Previous FAQ