Troubleshooting

The most common Headmaster Desktop issues, with the shortest fix that works.

"Runtime not connected" banner

The runtime is the background service. When it stops responding, the app shows a banner at the top of the chat.

Quick fix:

1. Open Settings → Headmaster's Library → Runtime → Restart.
2. Wait five seconds.
3. The status indicator should flip back to Connected.

If the restart doesn't help:

1. Open the log file at <data folder>/logs/<today>.log.
2. Look for the last error before the banner appeared. Most common: missing provider credentials, a port conflict, or a runtime that crashed on startup.
3. If you see a port conflict, close any other Headmaster windows and any other app that might be holding the port.

Last resort:

1. Quit Headmaster fully (close all windows; on macOS also Cmd+Q).
2. Wait ten seconds.
3. Reopen.

"401 Unauthorized" on Memory, Skills, or Runtime tabs

A 401 means the app and the runtime have lost their shared session token. This usually happens after a runtime restart that the app didn't see.

Quick fix:

1. Open Settings → Headmaster's Library → Runtime → Restart.
2. The new runtime issues a fresh token.
3. Reload the page you were on.

If 401s keep coming back: The runtime is restarting in a loop. Open the log and look for the error before each restart. Most common cause: a malformed config.yaml from a manual edit. Fix the config file and restart.

Runtime crash-restart loop

If the runtime exits immediately after starting (you see "runtime exited code=1" repeatedly in the logs):

1. Check the log file for the last error before the exit.
2. Common causes:
   • Missing dependency — on Linux, a missing libgtk-3 or libnss3 package.
   • Corrupted config — a syntax error in config.yaml.
   • Port conflict — another process is holding the port Headmaster needs.
   • Permission issue — the data folder is not writable by the current user.
3. Fix the underlying issue.
4. Restart Headmaster.

"Check for updates" returns nothing

The updater talks to the Headmaster release endpoint. If it can't reach it, you see an error in the update modal.

Quick fix:

1. Check your network connection.
2. If you're on a corporate network with a proxy, the release endpoint may be blocked. Ask your network admin to allow gcaplabs.com.

Manual update:

1. Download the latest installer from the Headmaster site.
2. Run it over the existing install.
3. Your data is preserved.

Update Modal says "Update available" but won't install

The installer needs write access to the install location. If you installed as an admin user and are now running as a non-admin user, the install will fail.

Fix: Run Headmaster as the same user that installed it, or reinstall in portable mode and copy your data folder over.

A chat won't load

If a specific conversation won't open but others do:

• Interrupted session: The session may have been interrupted mid-stream. The chat composer's draft is preserved. Click the conversation, wait for the recover prompt, and click Recover.
• Corrupted transcript: The transcript on the runtime may be corrupted. Open Settings → Headmaster's Library → Runtime → Sessions, find the session ID, and delete the local cache. The conversation will reload from the runtime's copy.
• Missing model: If the model used in the conversation is no longer available (provider key revoked, model deprecated), the conversation may fail to load. Add the provider back or switch the conversation's model.

White screen on launch

If the main window shows a blank white screen after launch:

1. Check the log file for renderer errors.
2. Common cause: a corrupted renderer cache. Delete the cache folder:
   • Windows: %APPDATA%\Headmaster\cache\renderer
   • macOS: ~/Library/Application Support/Headmaster/cache/renderer
   • Linux: ~/.config/Headmaster/cache/renderer
3. Restart Headmaster.

Port conflict

If another application is using the port Headmaster needs:

1. Open the log file and look for "port already in use" or "EADDRINUSE".
2. Find the process holding the port:
   • Windows: netstat -ano | findstr :<port>
   • macOS/Linux: lsof -i :<port>
3. Stop the conflicting process or reconfigure it to use a different port.
4. Restart Headmaster.

Runtime won't start on Linux

Common Linux-specific issues:

• Missing libraries: Install libgtk-3-0, libnss3, libasound2, libxss1.
• Permission denied: Make sure the data folder is owned by the current user: sudo chown -R $USER:$USER ~/.config/Headmaster.
• AppImage won't run: Make sure it's executable: chmod +x Headmaster-*.AppImage.
• Running as root: Add --no-sandbox flag.

Log collection for bug reports

When reporting a bug, attach:

1. The most recent log file from <data folder>/logs/.
2. The Headmaster version (from Settings → About).
3. Your OS and version.
4. Steps to reproduce the issue.

Use Settings → About → Report a bug to send this automatically.

Report a bug

Use Settings → About → Report a bug. The report:

• Attaches the most recent log file.
• Includes your app version and OS info.
• Includes the last 5 conversation IDs (not the content — just the IDs, for correlation).

Still stuck

Email admin@gcaplabs.com with the log file attached and a description of what happened.

---