Troubleshooting

Symptoms grouped by area. Find the heading that matches what you see, follow the steps, escalate if it’s still broken. If your problem isn’t here, email support@theagentum.com with what you’ve already tried.

The two universal fixes, worth trying before anything below:

  1. Restart the agent — System → Services → Restart. Restarts the background agent process in a few seconds without touching the app.
  2. Quit and reopen Agentum (⌘Q, relaunch). Everything Agentum runs — the agent, the local API, the tunnel — lives inside the app’s own process tree, so a clean relaunch resets all of it. There’s nothing left running in the background to clean up.

A note on names and paths. The product is Agentum; app state lives under ~/Library/Application Support/Agentum/. You may still see the older name YuriClaw in a few places (the yuriclaw:// link scheme, tunnel hostnames ending in .yuriclaw.com). Same system — both are correct. And if any guide tells you to run docker, podman, or edit a .env file, it’s describing an old version — none of that exists anymore.

License and sign-in

The account chip is missing or stuck on “Verifying…”

The license manager couldn’t read its cache or reach the server.

  1. Check your internet connection.
  2. Open the Account menu (sidebar footer) and click Reactivate — it re-runs the browser sign-in and forces a fresh verify.
  3. Quit Agentum (⌘Q) and relaunch — verification re-runs at boot.
  4. Still stuck? Email support@theagentum.com with the email you signed in with.

Sign-in completes in the browser but the app doesn’t notice

The browser hand-back (yuriclaw:// deep link) didn’t route to the app — some browsers block custom URL schemes.

  1. Make sure Agentum is running before you finish sign-in.
  2. Just wait on the app’s sign-in screen — Agentum also polls for the completed sign-in and normally picks it up within ~10 seconds without the deep link.
  3. If it never lands, quit, relaunch, and try Sign in with Google again, making sure you pick the right Google account.

I bought a license but the app still says trial/expired

  1. Open the Account menu → Reactivate (forces an immediate verify).
  2. Quit and relaunch — verify runs again at boot.
  3. Check email for your Stripe receipt; if 5+ minutes have passed since payment with no change, email support@theagentum.com with the receipt and we’ll reconcile.

Switching Google accounts

Agentum binds to whichever Google account activated the license.

  1. In your browser, sign out of the unwanted account at accounts.google.com (or it will auto-select again).
  2. In Agentum: Account menu → Reactivate, and sign in with the right account.
  3. To transfer an existing license between emails, contact support@theagentum.com.

Full-screen “license no longer active” overlay

The server marked the license revoked/expired (refund, chargeback, cancelled trial, or expiry).

  • Your agents stop, but nothing is deleted — config, agents, and data stay on disk, and the account UI stays available.
  • If this is unexpected, email support@theagentum.com — we can re-issue.
  • Buying or reactivating clears the overlay on the next refresh; everything resumes where it left off.

Going offline for a while

You get 7 days of offline grace from the last successful check. Before a long offline stretch, open Agentum once while online (that runs the daily check and restarts the 7-day clock). An amber banner warns near the end of grace; past it, agents pause until you’re back online.

The agent process

Agents aren’t running / everything looks dead

  1. Is Agentum actually open? The agents run inside the app — quitting the app stops them (that’s by design).
  2. System → Services — what does the Agent card say?
    • Stopped → click Start.
    • Crashed / Restarting → the app auto-restarts it with backoff; if it keeps crash-looping, see the next symptom.
    • Running → the problem is probably one agent, not the process; check System → Advanced → Health.
  3. Optional deeper check from Terminal: curl http://127.0.0.1:18790/api/health should return {"status":"ok"} while Agentum is running.

“No folder access” on the Agent card

Your agents folder is in a location macOS protects (Documents, Desktop, iCloud Drive) and the app hasn’t been granted access. A restart can’t fix this — it’s a macOS privacy setting. The card walks you through it: Open Privacy Settings, allow Agentum under Files and Folders (or Full Disk Access), then Relaunch Agentum.

One agent is failing (health badge, error banner)

  1. Click the health badge in the sidebar footer (or the agent’s own error banner) — it takes you to the failing agent with the actual error message.
  2. Read the error. Most agent failures are a missing integration (grant it, or finish its setup checklist in the Guide tab) or a bad setting (fix it in the agent’s panel).
  3. If the agent was auto-disabled after repeated failures, the banner offers Re-enable once you’ve addressed the cause.
  4. For your own agents: the Improve flow’s fix banner can turn the error trail into a repair task automatically.

An agent isn’t firing on schedule

  1. Open System → Advanced → Schedulers and find the agent’s job.
  2. No row? The agent never registered its schedule — if it’s yours, check init() registers the job; if it’s from the marketplace, reinstall or report it.
  3. Last fire is stale? Confirm the agent is enabled; restart the agent process. Remember your Mac must be awake for schedules to fire — Agentum doesn’t wake a sleeping Mac.
  4. Red status with an error? The job runs but throws — see the previous symptom.
  5. Fires but nothing visible happens? Check ⋯ → Integrations on the agent: a revoked grant makes well-behaved agents silently skip the blocked action.

A new hand-built agent doesn’t appear in the sidebar

  1. Confirm the folder is under your agents directory (System → Services → Agents folder shows the path; default ~/Documents/Agentum/agents).
  2. Confirm there’s a valid manifest.json at the folder root (valid JSON, unique id).
  3. Restart the agent (System → Services → Restart) to force a rescan.

Integrations

Google (Calendar/Gmail) says not authorized

  1. System → Settings → Profile → Google account → Re-authorize and step through the consent screen, approving the scopes.
  2. On a Google Workspace (organization) account, your admin may need to allow the app.
  3. Stale grant? Visit myaccount.google.com/permissions, remove the Agentum entry, and connect from scratch.

Telegram bot isn’t responding

  1. System → Settings → Bot & messaging — confirm the Bot Token is present (reveal toggle) and your numeric ID is in Allowed Telegram User IDs (from @userinfobot).
  2. Confirm you’ve pressed Start on the bot in Telegram — bots cannot message you first. Agentum’s test send detects this and tells you.
  3. Save, then Restart agent when the banner appears — token/allowlist changes need it.
  4. Still silent? Re-run the illustrated Show setup walkthrough on the same card end to end. See Telegram Setup.

Remote Access, Mini App, and Web Chat

The tunnel won’t start, or the public URL errors

  1. System → Settings → Telegram Mini App — check the status. Toggle Disable / Enable remote access to reprovision.
  2. Right after enabling, a Cloudflare 1033 / 530 error page is normal for a few seconds while edge DNS catches up. Give it a minute.
  3. Corporate/hotel networks sometimes block the tunnel’s outbound connection — try another network to confirm.
  4. Persisting? Quit and reopen Agentum (the tunnel restarts with the app).

Mini App / Web Chat worked before, unreachable now

Your Mac is the server. Is it awake and online? The tunnel drops when the Mac sleeps and reconnects on wake — this is the single most common cause. Keep the Mac awake (System Settings → Energy) for anywhere-access.

Mini App opens but says unauthorized (401)

  1. Close it and re-open from the bot’s menu button — Telegram re-signs the session on every launch, and stale sessions expire.
  2. Persistent 401s mean the bot token in Agentum doesn’t match the bot you’re chatting with, or your ID isn’t allowlisted — fix in Bot & messaging, Save, Restart agent.
  3. Don’t test the Mini App URL in a desktop browser — only Telegram can produce valid credentials, so a plain browser visit always fails. That’s the security model working.

theagentum.com/mychat says my chat isn’t ready

The front door only knows about your install after your Mac checks in with Web Chat enabled.

  1. Confirm Remote Access is enabled, then Web Chat is enabled (two separate cards in Settings).
  2. Make sure the Mac is awake; give it a couple of minutes to report in, then reload the page.
  3. Signed into the wrong Google account in the browser? Use the same one as your Agentum license.

Web Chat pairing or notifications misbehaving

  • Pairing requests appear on the Mac (banner + System → Settings → Paired devices). No prompt? Make sure the desktop app is frontmost and the request hasn’t expired (codes are short-lived) — start pairing again from the browser.
  • To kill a lost device’s access: Paired devices → Revoke (or Revoke all). It’s immediate.
  • No push notifications? Allow notifications when the web app asks, and remember push is sent by your Mac — asleep means silent.

Updates and installation

An update downloaded but won’t install

  1. Quit Agentum fully (⌘Q) and relaunch — a downloaded update applies on the next clean launch.
  2. Make sure the app is in /Applications (not running from the DMG or Downloads) — macOS can’t swap an app bundle anywhere else.
  3. Last resort: download the latest DMG from theagentum.com/download and drag it over the old app. Your data in ~/Library/Application Support/Agentum/ and your agents folder are untouched.

Gatekeeper blocks the app on first launch

  1. Right-click Agentum.app → Open → Open. One-time.
  2. Or System Settings → Privacy & Security, scroll down, Open Anyway.
  3. If macOS says the app is damaged or unnotarized, you likely have a corrupted or unofficial download — re-download from theagentum.com/download.

Reinstalling — what survives

Replacing the app bundle touches nothing else:

  • Survives: ~/Library/Application Support/Agentum/ (settings, license cache, agent data, tunnel credentials) and your agents folder (~/Documents/Agentum/agents by default).
  • Replaced: just /Applications/Agentum.app.
  • For a true clean slate, also delete the Application Support folder — you’ll re-run onboarding and reactivate. (Prefer the gentler System → Advanced → General → Re-run onboarding, which keeps your license and agents.)

See also