Troubleshooting
Fixes for sign-in, Cloud access and model issues
Find the problem you are seeing, then follow the steps in order. Most issues are fixed by the first or second step. If nothing here helps, see Still stuck at the end.
Before you start
These three checks fix a lot of problems:
- Check your internet connection. Cloud mode, web chat and Headmaster models all need it.
- Check which mode you are in. Cloud and Work behave differently. See Cloud and Work modes.
- Make sure you are up to date. Open Settings → Version & updates and choose Check now. See Updating Headmaster.
Signing in
I cannot sign in
- Check your email and password. Use Forgot password? to reset it.
- If you signed up with email, confirm your address from the message we sent. Check your spam folder.
- If you signed up with Google, choose Continue with Google and pick the same Google account.
- Signing up with email and later choosing Google, or the other way round, can look like a different account. Use the method you started with.
"This account is not approved to use Headmaster yet."
Public sign-up is closed during the beta. New Cloud accounts are approved one by one. Contact us to ask for access. Work mode in the desktop app does not need Cloud approval.
"Sign in again"
Your session expired. Sign in again. Your chats and settings are safe. Nothing is deleted when a session expires.
Cloud mode and web chat
"Your Cloud workspace is still being set up"
Your account was just approved and your workspace is being prepared. This usually takes a minute or two. Wait, then send your message again.
"No workspace is set up for this mode yet."
Your account does not have a Cloud workspace. Cloud access is approved account by account during the beta. Contact us. Work mode still works.
"Headmaster Cloud isn't available for chat right now."
Your Cloud workspace cannot be reached at the moment. Wait a minute and try again. If it keeps happening, contact us.
The app says it is reconnecting
Headmaster reconnects on its own. You can keep reading and drafting while it does. If it says Still trying to reconnect:
- Check your internet connection.
- Choose Reconnect now.
- Switch mode and back, or restart the app.
"Headmaster is offline right now"
An action could not be sent because the connection dropped. Choose Reconnect, then send it again. If an approval was waiting, it stays waiting until it times out.
I cannot switch to Cloud or Work
The switch shows Couldn't switch to Cloud Mode or Couldn't switch to Work Mode with a reason.
| Reason | What to do |
|---|---|
| Sign in again to switch modes. | Sign in, then switch |
| A mode change is already in progress. | Wait for it to finish |
| Could not connect. Try again. | Check your connection, then Retry |
| Could not confirm the switch. Try again. | Choose Retry |
Regenerate does not work in web chat
Regenerating or continuing a reply is not supported in web chat yet. Send a new message to keep going instead.
Work mode
The agent cannot see my files
- Check you are in Work mode. Cloud mode cannot see your PC.
- Check the working folder. The agent works inside the folder you chose.
- Check approvals. With Manual, the agent waits for you to approve file changes and commands.
Memory says "Memory unavailable in Work mode"
The Memory page browses your memory from Cloud. Switch to Cloud to browse it. The agent still uses your shared memory in Work mode.
Switching to Work mode is slow
The local Work engine starts when you switch. To make switching instant, turn on Keep Work engine running while in Cloud in settings. When it is off, the engine stops after 30 idle minutes in Cloud.
Models and replies
A model is missing from the picker
- If it is one of yours, open Settings → Providers and check the key. A key that cannot be read shows Re-enter your key. Replace it.
- If you removed a key, its models disappear. If you were using one, Headmaster switches to Lite and tells you.
- In web chat, if you see That model isn't available right now, open the model picker and choose one from the current list.
I reached a usage limit
Headmaster models have usage limits during the beta. You might see:
- You've used today's Headmaster Lite allowance. It resets the next day.
- You've used this month's Headmaster allowance. It resets on the 1st of next month.
Either way, you can choose Connect your provider to keep going with your own model. See Models and providers.
Common reply errors
| Message | What to do |
|---|---|
| The AI service is busy | The provider is limiting requests. Wait a minute, then retry |
| The AI service is overloaded or had a problem | Retry in a moment, or switch model |
| The reply timed out or was cut off | Retry to send it again |
| This conversation is too long | Compress the chat or start a new one, then send again |
| This message is too large | Make the message or attachment smaller, or start a new chat |
| This model is not available | Your provider does not offer that model to you. Pick another |
| The AI service declined this request | Edit the message and send again |
| Headmaster got stuck in a loop | Retry, or start a new chat if it happens again |
| This chat is open somewhere else | Close it in the other window, or start a new chat here |
| Disk full | Free some space on your PC, then retry |
You can type /retry in the chat box to resend your last message.
Approvals
The agent is waiting and nothing happens
It is probably waiting for your approval. Look for the approval prompt in the chat and choose to approve or deny. See Approvals and safety.
The agent did something without asking
Check your approval mode in the chat box. Off runs without prompts. Set it back to Manual.
Updates and install
Windows warns about the installer
The installer is not code-signed yet. Choose More info, then Run anyway.
An update did not finish
Nothing was lost. Try again from Settings → Version & updates. If it keeps failing, download the installer from the download page and run it over your install. See Updating Headmaster.
Still stuck
Contact us and tell us:
- what you were doing,
- the exact message you saw,
- whether you were in Cloud, Work or web chat,
- your app version from Settings → Version & updates.
If the app offers Copy diagnostics, it copies a report to your clipboard that helps us find the problem. Nothing is sent automatically. The report can include parts of your conversations and file paths, so read it before you share it.