Troubleshooting

Most of it is in the daemon's log:

tail -f ~/.huskarl/logs/huskarld.log

It is written when the daemon runs as a login item, as a developer LaunchAgent, and when the window has started it itself. If you run huskarld by hand in a terminal, the log goes there. RUST_LOG=debug gives more.

The Keychain asks after every rebuild

The Keychain grants access per code signature. A plain cargo build is signed ad hoc, and every rebuild is a new program to the Keychain. macOS then asks again for access to the mail logins, also in the middle of a routine at night, when nobody is there to answer.

• Run huskarld check <bot> right after a new version, and choose "Always Allow". The question then comes while you are sitting there.
• With a Developer ID it goes away: scripts/bundle.sh signs with one if the Keychain has one, and a release is always signed. The Keychain then sees the same program after every build.

The window does not connect

If the log says the protocols differ ("the app speaks protocol X, this daemon Y; update the older one"), the app and the daemon are from different versions. Update the older one. If a developer LaunchAgent is running with an old copy in ~/.huskarl/bin, that is usually it.

The daemon is not running

From the terminal: huskarld is not running (/Users/…/.huskarl/run/huskarld.sock).

• The packaged app: check that Huskarl is turned on under System Settings → General → Login Items. The app opens that page itself when macOS requires approval. Start Huskarl.app once after you have turned it on.

• The developer LaunchAgent:

  launchctl print gui/$(id -u)/no.huskarl.daemon | grep -E 'state =|pid ='
  

  and look in the log.

• huskarld is already running: a daemon is already running on the socket. Only one can run per HUSKARL_HOME.

• "the database is from a newer Huskarl (schema N, this build knows M)": the database has been upgraded by a newer version. Use the newer version.

The packaged app and the developer LaunchAgent at the same time would give two daemons. The app therefore removes no.huskarl.daemon when it starts from a bundle.

The bot does not answer: the agent

The error is in the thread, in red, and the bot stays marked as failed.

In the settings, "Not connected to Huskarl" appears next to Claude Code or Grok Build when Huskarl's own login is missing, and "The login was refused: sign in again" when the provider has refused it in a run. Press Connect …. The mark goes when you have signed in again, or when a run with that agent goes through. Your own login in ~/.claude or ~/.grok does not count. See Agents.

PATH. Started by launchd, the daemon gets only /usr/bin:/bin:/usr/sbin:/sbin. It therefore takes PATH from your login shell. If the log says "the login shell did not answer within 5 s; keeping launchd's PATH", something in .zprofile or .zshrc is waiting for input. Make it quiet for non-interactive shells.

A login shell does not read ~/.zshrc, where Grove, nvm and Volta put node. When an agent is a script that runs with node (Elyra's cli.js) and the daemon's PATH lacks it, Huskarl looks for it beside the script, in those version managers' folders, and in /opt/homebrew/bin and /usr/local/bin, and puts the folder it finds first on the agent's PATH.

The change did not take effect yet. If you save settings while the bot is in the middle of a turn, the running agent finishes that run first, and is restarted with the new settings afterwards. See Agents.

The agent cannot reach the model

Look in the log for egress:

egress REFUSED api.example.com:443 for Some("<bot-id>") (0 up, 0 down)

The proxy only lets through the hosts of the bot's model provider (see Agents). If the bot uses a provider Huskarl does not know, it says "no known hosts for provider …; its agent can reach no model". Choose a model from a known provider.

Claude Code renews its login through the proxy (platform.claude.com). If you get a login error from Claude Code or Grok Build after a while, look for REFUSED with a host that is not on the list. If nothing was refused, the provider refused the login itself: see the table above.

The model stopped in the middle of the turn

The provider can cut a turn short, for example with a content filter. The turn then ends with the provider's error in the thread and without a summary. Nothing has been sent because of it. Write a new message to try again.

The run stopped at the budget

"The run was stopped: it has used N tokens of its budget of M. …" Write "continue", or raise Tokens per run.

"The day's budget ($X) is used up ($Y today), so … did not run." Routines, tasks and Félagi issues wait until tomorrow. Messages you send yourself are run.

Mail

• The browser does not open on "Connect". From the terminal, huskarld connect <bot> gmail prints the address, which you can open yourself. You have 10 minutes.
• A company tenant says no. An administrator may have to consent to the app, or the tenant blocks apps from unknown publishers.
• Gmail stops working after a week. A Google project in testing mode gives logins that expire after 7 days. Connect again.
• The Keychain: see the top.

huskarld check <bot> says whether the mailbox answers, and whether the search for new mail works.

The browser

"Opening the browser…" stays. The panel is waiting for an answer the daemon could not give. Most often:

• There is no Chromium on the machine. Install Chrome, or set HUSKARL_CHROME for the daemon. The error is "found no Chrome or Chromium on this Mac".
• The bot has no websites ("the bot has no sites it may use").

The error is in the log.

A page does not open. If the log says browser: refused <address>, the page is not on the bot's list. Remember that redirects are checked too: a login that goes through another domain needs that domain on the list as well.

The bot says the user is in control. You have taken over. Press Give back, or close the panel.

"the element is now called …". The page has changed since the bot looked at it. The bot takes a new snapshot itself.

Routines

A routine that did not run:

• Is it paused? huskarld routines shows (paused), and the chip "· paused".
• Was the bot busy? The log: routine <id> skipped: its bot is busy.
• Was the daily budget used up? It says so in the thread.
• Does it have a condition? Then it only runs when something new has happened since last time. For new_mail: huskarld check <bot> shows how many emails came in the last 24 hours.

Webhook gives 404. The token is wrong, or the routine is paused. No answer at all: if the log says webhooks: cannot listen on 127.0.0.1:47811, the port is taken. Set HUSKARL_WEBHOOK_PORT.

Proposals marked "Uncertain – check"

The daemon stopped while it was carrying out the proposal. It may have happened, or not. Huskarl never tries again on its own. Look in the service, for example in the Sent folder, and ask the bot to send again if it did not go through.

Notifications

• No notifications: they are not sent while a Huskarl window is in front.
• No system notifications: they are sent with osascript. Check that notifications for Script Editor are allowed under System Settings → Notifications. If HUSKARL_NOTIFY=off is set for the daemon, they are not sent.
• Nothing on the phone: subscribe to exactly the topic the settings show. The log has ntfy: … when publishing fails.

Félagi

huskarld felagi status shows the error. From Félagi it comes as "Félagi answered : ".

sqlite3 ~/.huskarl/huskarl.db "SELECT * FROM audit_log WHERE id >= <id> - 1 LIMIT 3"