Troubleshooting by symptom

Asking inside the app

Before working through this page, you can also ask the app directly. The ? button at the top right (next to the ⚙ settings button) opens two doors.

Door	What it does
🎓 Watch the feature tour	Walks you through the main features, highlighting the relevant button on screen as it goes (7 steps, about a minute — skippable at any point)
❓ Open the usage Q&A thread	A thread where you can ask anything about features and how to use them

The Q&A thread answers from the bundled usage guide (12 knowledge documents) and cites its source. That guide is registered as the knowledge item How to use WorkPilot, so you can browse and search it like any other knowledge. It updates itself as the app updates.

The thread's name carries the version — ❓ How to use WorkPilot v0.3.340, say. Updating never adds a second one. The same thread becomes the current version's, with a note on what changed. Anything you don't follow, ask right there in the same thread.

Clearing it away is fine

If you don't want the ❓ thread, archive it or delete it — it stays gone for the rest of this version. It returns only on the next update, as that version's guide. Want it back sooner? Reopen it from ? at the top right.

Find your symptom

What's happening	Go to
The app won't open or won't update	The app won't start or update
A Terminal window appeared and I'm lost	Terminal is confusing
Claude or ChatGPT won't connect	The connection test fails
Video won't generate	Video won't generate
Images or audio won't generate	Images or audio won't generate
The AI ignores what I asked	The AI's answers are off
It runs away / I can't stop it	I don't know how to stop it
Everything is slow	It feels sluggish
I can't find what I made	I can't find a file
I deleted something	Getting deleted things back
Team sharing won't sync	Sharing isn't working
My phone can't connect	The phone remote won't open

Three things to try first

Whatever the symptom, these three fix it more often than not.

Start a fresh thread
The conversation may simply have got too long and tangled. Ask the same thing in a new thread.
Reset the session
⟳ Reset session in the thread menu. The conversation stays; only the AI-side state is rebuilt.
Restart the app
Quit and reopen. Nothing is lost.

The app won't start or update

Symptom	Cause	Fix
“Cannot verify the developer”	macOS protection	Right-click the app → Open → Open. If that fails, System Settings → Privacy & Security → Open Anyway
“Downloaded from the Internet”	The normal first-launch check	Press Open to continue
Updates won't apply	Where the app lives	Check it's in the Applications folder. Running from inside the DMG or the desktop blocks updates
No update is found	Waiting on a check	Settings → About → Check for updates. If current, it says Up to date

Terminal is confusing

It's the plain-text window that opens during sign-in. You do not need to type anything.

What you see	What to do
A list of options	Use `↑↓` then `Enter`. The mouse won't work
Text scrolling endlessly	It's installing. Wait for it to stop
“Paste the code”	Copy the code from the browser, then `⌘`+`V` and `Enter` in Terminal
It looks finished	Close the window (`⌘`+`W`) and press Test connection in the app
I closed it by mistake	No problem. Start again from the button — as many times as you like
I can't find the window	It's behind something. Click Terminal in the Dock

About safety

The only thing running here is the official sign-in tool published by each AI vendor. Your username and password are entered on the vendor's own web page and never pass through WorkPilot.

The connection test fails

Work down the list. It's almost always the first or second item.

Did you press “Test connection”?
Signing in doesn't mark anything as connected. You have to come back and press the button.
Did sign-in actually finish?
Approving in the browser and seeing success in Terminal is one complete round. If you closed it partway, start again.
Did you sign in with the account you pay for?
With several accounts, it's easy to sign in as whichever one your browser remembered. Signing out in the browser first makes it certain.
Is the subscription active?
An expired or unpaid subscription can't connect. Check on the vendor's site.
Is the auth method right?
If the Claude row is set to Use an API key, it looks for a key even though you signed in. Switch to Sign in with subscription (recommended).
Check everything at once
Settings → Connections → Diagnose all services shows where things stop in one pass.

Message	Meaning
Cannot connect. Check that you are signed in to Claude.	Claude sign-in didn't complete
You need to sign in to ChatGPT…	ChatGPT sign-in didn't complete
kimi-cli is not installed.	The Kimi program isn't there yet
You are not signed in to Kimi.	Installed but not signed in. A subscription is also required

The full walkthrough is in How subscription sign-in works.

Video won't generate

Is the engine Claude?
Check AI engine at the top right. Video only runs through Claude.
Is Higgsfield connected?
Press Re-authenticate / test and look for a credit number. Text alone isn't enough.
Are there credits left?
An empty balance can't generate. Check on the Higgsfield side.
Have you hit a cap?
Check the daily and monthly limits under Settings → Usage.
Is the mode “Video”?
In chat mode you'll get a written answer instead of a video.

Images or audio won't generate

Symptom	What to check
No images	Whether the OpenAI image API key is saved (🔐 Saved in Keychain)
No narration	The ElevenLabs key. Without the Voices: Read permission it can't load voices
No music	Also the ElevenLabs key — music permissions are required
Can't record	Microphone permission: System Settings → Privacy & Security → Microphone
Auto-subtitles fail	Speech recognition permission, in the same place

The AI's answers are off

Symptom	Usual cause	Fix
It ignores the context	No knowledge equipped	Equip it from 📚 Knowledge, roles, connections
It drags in unrelated things	Over-equipped, or a long conversation	Remove what isn't needed. Use 📖 Continue in a new chapter
It forgets earlier decisions	The conversation grew too long	Start a chapter. Put decisions into knowledge
Quality varies each time	The approach isn't settled	Turn a good run into a skill
Answers are shallow	The request is abstract	Specify the output shape — table, bullets, length
It stops halfway	The work doesn't fit one reply	Turn on Run to completion in the composer

I don't know how to stop it

What to stop	How
The AI mid-task	`Esc`
Something you just sent	`Esc` within 5 seconds — the text returns to the field
An autonomous run	Stop, or `Esc`
The twin's auto replies	Stop auto mode — though a reply already on screen finishes
A scheduled loop	Switch off Run on schedule for that loop
Automation in general	Set approval mode back to Ask every time under Settings → Safety

What stopping does not undo

Esc stops further work, but files already written and messages already sent externally stay done. For work that includes anything irreversible, keep approval mode on Ask every time.

It feels sluggish

Symptom	What to do
Replies are slow	The conversation is too long. Break it with 📖 Continue in a new chapter
The UI stutters	Archive threads you're done with to lighten the list
It stalls midway	Possibly plan usage limits. Check Settings → Usage
Work mode keeps stopping	It reached the auto-continue limit. Send anything to resume

I can't find a file

Search the file manager
Search by name or thread, and filter by kind — video, image, audio, documents.
Open it from the thread
📂 Open the storage folder in the thread menu reveals that thread's folder.
Check the storage folder
Settings → Data → Open. The default is Documents/WorkPilot.
Added it in Finder but it isn't showing?
Press Refresh in the media pool.

What goes in which folder is covered in where data lives.

Getting deleted things back

What you deleted	Recoverable?	How
A thread (pressed ✕)	Yes	Restore it from Archive in the sidebar
A media file	Yes	It only went to the trash. Restore it from Finder
A thread you actually deleted	From a backup	Settings → Data → Backup, pick a date and restore
An item in a team space	No	It's gone for every member. Read the confirmation dialog carefully

Restoring is also reversible

When you restore from a backup, the current state is set aside automatically — so “I restored it but preferred what I had” is recoverable too. The app restarts to apply it.

Symptom	What to do
⚠ Cannot connect	The shared folder is missing or unwritable. Check your NAS or cloud mount
The join code is rejected	Copy and paste it again, watching for stray spaces
“The shared folder hasn't reached this Mac yet”	The folder hasn't been shared on the cloud side. Ask the leader, then retry after it syncs
They can't see the documents I shared	You may have shared only the thread, not the knowledge
⛔ …sharing is paused	The leader paused it. Ask them to resume

The phone remote won't open

Is WorkPilot running on the Mac?
The remote does nothing if the app is closed.
Are you on the same Wi-Fi?
At home or in the office, that's all it takes.
Away from your desk — is Tailscale installed?
If you see ⚠ Tailscale not found…, it won't reach from outside.
Is the URL current?
Rotating the key invalidates the old URL. Open the new one.

If none of this helps

Settings → About → Open log folder gets you the logs. When reporting a problem, three things make it much easier to diagnose:

What you were trying to do and what happened — quote the on-screen wording
The app version (Settings → About)
The contents of the log folder