Troubleshooting

Symptoms grouped by area. Find the heading that matches what you see, follow the numbered steps, escalate if it’s still broken.

If your problem isn’t here, see Account & billing or Getting started — and email support@theagentum.com with whatever you’ve already tried.

Note on file paths. The product is called Agentum, but the on-disk data directory is ~/Library/Application Support/YuriClaw/, the env vars are prefixed YURICLAW_*, and the URL scheme is yuriclaw://. These predate the rebrand and are deliberately unchanged so existing installs survive the upgrade — your data and license stay put. References to YuriClaw in paths and identifiers below are correct as written.

License issues

Symptom: “Trial — Nd” chip is missing or stuck on “Verifying…”

The license manager couldn’t read your license cache or talk to the server.

  1. Check your internet connection.
  2. Open System → Advanced and click Reactivate.
  3. If that fails, quit Agentum (Cmd+Q), wait a few seconds, and relaunch — the manager re-runs verify on launch.
  4. If it’s still stuck after a relaunch, the cache may be corrupt. Quit Agentum, move ~/Library/Application Support/YuriClaw/license.json to your Desktop, and relaunch — the app will re-fetch from the server.
  5. Still stuck? Email support@theagentum.com and attach the contents of ~/Library/Application Support/YuriClaw/settings.json (it has your licenseKey but no secret data).

The OAuth callback fires agentum://license?key=… but macOS doesn’t route it back to a running app.

  1. Make sure Agentum is running before you click the activation link.
  2. In your browser, copy the activation URL from the address bar and paste it into a new Safari window — Safari handles custom URL schemes more reliably than Chrome on first install.
  3. As a fallback: the wizard polls /api/licenses/activation-status every few seconds. Just leave Agentum’s onboarding screen open — within ~10s of completing Google sign-in, it picks up the new license without needing the deep link.
  4. If polling also fails, copy your license key from the email Stripe sent and paste it into the “I have a license key” field on the LicenseStep.
  5. Still broken? Email support@theagentum.com with the email you signed in with.

Symptom: I bought lifetime but the app still shows “Trial expired”

The Stripe webhook hasn’t been processed, or the heartbeat hasn’t run since.

  1. In Agentum, open System → Advanced → Reactivate. This forces an immediate verify.
  2. If your trial entry is still showing, quit and relaunch — the verify runs again at boot with the same licenseKey and the server will return the upgraded record.
  3. Check your email for a Stripe receipt. If you have one, the webhook normally fires within seconds; if more than 5 min has passed without an in-app upgrade, something dropped on the server side.
  4. Email support@theagentum.com with the Stripe receipt’s payment intent ID (pi_…) and we’ll reconcile manually.

Symptom: Sidebar shows the wrong account / I want to switch Google accounts

Agentum is signed in with whichever Google account first activated the license. To swap:

  1. Open System → Advanced → Sign out.
  2. Quit Agentum (Cmd+Q).
  3. In your browser, sign out of the unwanted Google account at accounts.google.com (otherwise it’ll auto-select again).
  4. Relaunch Agentum and run the wizard from the top — choose Start trial or I have a license key and sign in with the right account.
  5. If you need to transfer your existing license to the new email, email support@theagentum.com with the old and new email addresses.

Symptom: Full red overlay says “license deactivated” but I haven’t been refunded

The server returned status=revoked, which the client treats as a hard block. Common causes: a chargeback was filed, payment failed retroactively, or the license was manually revoked for support.

  1. Check your email for a notice from support@theagentum.com or Stripe.
  2. Click the Contact support button on the overlay (it opens a mailto: to support).
  3. If you genuinely didn’t initiate a refund or chargeback, email support@theagentum.com immediately — we can re-issue.
  4. While you wait, the shell stays usable but containers won’t start. Plugin editing still works for offline drafts.

Symptom: Going to be offline for >7 days — how do I prep

The client gets a 7-day offline grace from the last successful heartbeat. After 7 days with no server contact, containers stop.

  1. Within the 24h before you go offline, open Agentum and let the daily heartbeat run (or click System → Advanced → Reactivate to force one).
  2. Confirm the sidebar chip says “Lifetime” or “Trial — Nd” — not “Offline” — that means you’re freshly verified and the 7-day clock starts now.
  3. Plan to come online within 7 days. If you can’t, accept that containers will stop until the next successful verify.
  4. Email support@theagentum.com ahead of time if you have a known longer offline window — we can sometimes extend grace on a case-by-case basis.

Symptom: “Sign in to your account” prompt keeps appearing but the chip won’t update

The legacy OAuth-polling path completed but the new license manager hasn’t picked up the key from settings.

  1. Quit Agentum and relaunch. The manager loads licenseKey from settings.json at boot.
  2. If the chip is still missing, open System → Advanced and check whether License key field is populated. If empty, paste your key from your activation email and click Save.
  3. Click Reactivate to force a verify.
  4. Still no chip? Email support@theagentum.com with your license key.

Container / runtime issues

Symptom: “Starting services” boot screen never finishes

compose up -d succeeded but at least one service is stuck in a non-healthy state. The boot waits up to 5 minutes before timing out.

  1. Wait the full 5 minutes — first-launch image pulls can be slow on a cold cache.
  2. Open the developer logs (View → Toggle Developer Tools → Console) and look for [ContainerManager] lines.
  3. Quit Agentum, then in a terminal: cd ~/Library/Application Support/YuriClaw/yuriclaw-data && docker compose ps — note any service in unhealthy or restarting state.
  4. If a single service is wedged, restart just that one: docker compose up -d --force-recreate <service>.
  5. Still stuck? Email support@theagentum.com with docker compose logs --tail=200.

Symptom: Podman machine isn’t starting

Agentum needs a running container runtime. Podman’s VM has to be initialized once and started after each reboot.

  1. Open Terminal and run podman machine list.
  2. If no machine exists: podman machine init then podman machine start.
  3. If one exists but is Stopped: podman machine start.
  4. If start fails with a virtualization error, make sure macOS allowed the Podman helper extension (System Settings → Privacy & Security, scroll to the bottom).
  5. Re-launch Agentum once podman ps returns without error. Still failing? Email support@theagentum.com with podman machine info output.

Symptom: Containers report “unhealthy” — how to inspect logs

  1. In Agentum, open System → Containers to see the per-service health pill.
  2. In a terminal: cd ~/Library/Application Support/YuriClaw/yuriclaw-data && docker compose logs --tail=100 <service> (or podman compose logs …).
  3. For a live tail: docker compose logs -f <service>.
  4. For raw inspection: docker inspect <container-name> shows the last health-check exit code and stderr.
  5. Capture the relevant log lines and email support@theagentum.com.

Symptom: Compose provider not available (the bundled docker-compose standalone is missing)

Agentum’s boot detection tries podman compose, podman-compose, docker compose, and docker-compose in order. If none answer, the app fails to start the stack.

  1. In a terminal: which docker-compose and docker compose version. At least one should print a version.
  2. If you have Docker Desktop installed, open it and let it finish starting — the docker compose plugin only registers once Docker Desktop’s daemon is up.
  3. If you’re on Podman, run brew install podman-compose and retry.
  4. As a last resort, reinstall Agentum from the latest DMG — Resources/runtime/docker-compose is bundled and re-extracted on install. (Note: the bundled binary is listed under mac.binaries in electron-builder.yml so notarization includes it; if it’s missing you have a partial install.)
  5. Still stuck? Email support@theagentum.com.

Symptom: After a macOS update, services stopped working

macOS point-releases occasionally reset virtualization permissions or evict cached Docker/Podman state.

  1. Open Docker Desktop or run podman machine start. Confirm docker ps (or podman ps) returns without error.
  2. Re-grant any permissions macOS revoked (check System Settings → Privacy & Security for newly-blocked items).
  3. Quit and relaunch Agentum. The boot sequence will re-sweep orphans and re-bring up the stack.
  4. If a Class-2 orphan dialog appears asking to remove old containers, click Remove and Start — your data on host volumes is preserved.
  5. Still broken? Email support@theagentum.com with the macOS version and docker version output.

OAuth / integration issues

Symptom: Google OAuth tab opens but never returns

The OAuth response is supposed to redirect back to Agentum via agentum://.... If the redirect doesn’t complete, the polling fallback eventually catches up.

  1. Leave the Agentum onboarding screen open. The wizard polls /api/licenses/activation-status and will pick up the completed sign-in within ~10s.
  2. If polling never lands, check the browser tab for an error from accounts.google.com (consent denied, account disabled, etc.) and retry.
  3. Sign out of any extra Google accounts at accounts.google.com so the OAuth picker doesn’t get confused.
  4. As a fallback, copy the license key from your activation email and paste it into Agentum’s “I have a license key” field.
  5. Still failing? Email support@theagentum.com.

Symptom: Calendar / Gmail integration says “not authorized”

The integration’s OAuth scopes weren’t granted, were revoked, or the refresh token expired.

  1. In Agentum, open the integration’s settings card and click Reconnect.
  2. Step through the Google consent screen; make sure the Calendar/Gmail scope checkboxes are ticked.
  3. If you see “This app is blocked”, check Google Workspace admin policies (org-managed accounts may require an admin to allow the app).
  4. Visit https://myaccount.google.com/permissions, remove any stale Agentum entry, and reconnect from scratch.
  5. Still broken? Email support@theagentum.com with the integration name.

Symptom: Telegram bot isn’t receiving messages

Either the bot token is wrong, your user ID isn’t in the allowlist, or the in-container TMA listener didn’t start.

  1. Open System → Settings → Telegram Mini App and confirm the Bot Token field shows a value (use the reveal toggle).
  2. Confirm your numeric Telegram user ID is in Allowed User IDs (comma-separated). Get it from @userinfobot if you don’t have it.
  3. Click Save, then Restart agent — this re-spawns the agent container with --force-recreate so the new env is picked up.
  4. Verify the listener is up: cd ~/Library/Application Support/YuriClaw/yuriclaw-data && docker compose logs agent | grep -i tma should show [TMA] listener up on 127.0.0.1:18803. If you see [TMA boot guard] refusing to start: TELEGRAM_ALLOWED_USER_ID is empty, your allowlist didn’t save — re-enter and re-save.
  5. Still no messages? Email support@theagentum.com with the bot’s @username.

Plugin / agent issues

Symptom: New agent doesn’t show up in the sidebar after I created it

The plugin folder watcher missed the new directory, or the manifest is invalid.

  1. Confirm the new agent’s folder lives under your configured plugins directory (default: ~/Documents/YuristicPlugs).
  2. Verify the folder contains a valid manifest.json at its root.
  3. Click the Reload plugins button in the sidebar header (or reload the window with Cmd+R).
  4. If the sidebar still ignores it, check the dev console for [plugins] errors — a malformed manifest fails silently in the list view.
  5. Still missing? Email support@theagentum.com with the manifest’s contents.

Symptom: Agent built by the chat builder failed validation

The builder generated a manifest or panel file that doesn’t pass schema validation.

  1. Read the validation error in the chat — it names the failing field (e.g. tools[2].schema.properties.input.type).
  2. Click Edit in builder and ask the builder to fix the specific field.
  3. If the builder loops, manually open the generated manifest.json and edit the field to match the schema (see Getting started for the manifest reference).
  4. Re-trigger validation by clicking Validate on the agent’s card.
  5. Still failing? Email support@theagentum.com with the manifest you tried to save.

Symptom: Plugin’s Configuration tab shows blank fields after I save

The fields saved to disk but the in-memory cache wasn’t refreshed.

  1. Reload the window (Cmd+R). The fields will repopulate from disk.
  2. If the values are still blank after reload, open ~/Documents/YuristicPlugs/<agent>/config.json and confirm your values are there.
  3. If config.json is empty or missing, the save handler failed. Re-enter your values and watch the dev console for [config] errors when you click Save.
  4. Still blank? Email support@theagentum.com with the agent name and the contents of its config.json.

Symptom: The hot-reload isn’t picking up my panel.js change

The chokidar watcher should fire on saves under the plugins directory, but only for files that match the watch glob.

  1. Confirm you saved the file (some editors don’t write until you blur the window or run a formatter).
  2. Confirm the file lives under your plugins directory — files outside ~/Documents/YuristicPlugs/ aren’t watched.
  3. Reload the window with Cmd+R to force a fresh read.
  4. Restart Agentum if the watcher itself died — check the dev console for chokidar errors.
  5. Still not reloading? Email support@theagentum.com with the absolute path of the file you’re editing.

Symptom: My agent isn’t firing on schedule

The plugin either didn’t register its recurring job, registered it under an unexpected name, or hit an error on every tick.

  1. Open System → Schedulers. Find your plugin in the grouped list.
  2. No row at all? The plugin didn’t call ctx.schedule.every(...) (or dailyAt) in its init(). Open the agent’s source and confirm; recurring jobs registered via the legacy manifest.tickIntervalMs field still show up here too.
  3. Row present but Last fire is —? Tick hasn’t fired yet. For a once-a-day schedule that’s normal; for every(N, …) it should have fired within the interval. Check that the plugin is Enabled in the sidebar.
  4. Row shows a red dot + error message? The tick fires but throws. The error message is truncated in the table; the full stack lives in the plugin’s Logs tab.
  5. Tick fires fine but nothing visibly happens? Check the Permissions tab: a revoked integration grant returns a denial — the tick will run, the ctx.services.X.isReady() guard will return false, and your code will silently skip the action. Toggle the integration back on.

Symptom: My agent stopped working after I changed a Permissions toggle

Revoking an integration or data-read grant is meant to keep the plugin running with reduced capability, but the plugin might not handle the denial gracefully.

  1. Open the Permissions tab for the affected plugin. Note which toggle you flipped.
  2. The plugin’s ctx.services.<id>.isReady() returns false for revoked integrations, and ctx.data.read(<id>, <table>) returns [] for revoked reads. Well-written plugins guard on these.
  3. If the plugin throws unhandled errors on revoked access, toggle the grant back on as a temporary fix, then check the plugin’s Logs tab for the unhandled-promise error message — that points at the un-guarded code path.
  4. Use Reset to defaults in the Permissions tab to restore the auto-granted state from the manifest.

Update / installation issues

Symptom: Auto-update notification appeared but install fails

electron-updater downloaded the new version but Squirrel.Mac couldn’t swap the bundle.

  1. Quit Agentum fully (Cmd+Q) and relaunch. The downloaded update will apply on the next clean launch via autoInstallOnAppQuit.
  2. If a system notification said “YuriClaw is updating” but the app never came back after ~30s, open Console.app and search for [updater] or Squirrel — the message App Still Running Error means a background helper kept the process alive past the install window.
  3. Make sure Agentum is in /Applications/ (not in the DMG, not in ~/Downloads/). Squirrel needs a writable, non-translocated location to swap the bundle.
  4. As a last resort, download the latest DMG manually from https://theagentum.com/downloads/yuriclaw/stable/ and drag the new app into /Applications, replacing the old one. Your data in ~/Library/Application Support/YuriClaw/ is preserved.
  5. Still broken? Email support@theagentum.com with the version you’re updating from and to.

Symptom: Gatekeeper blocked the .app on first launch

macOS shows “Agentum can’t be opened because Apple cannot check it for malicious software” or similar.

  1. Right-click (or Control-click) Agentum.app in /Applications and choose Open from the context menu — this surfaces a one-time Open button that bypasses the default block.
  2. If that doesn’t appear, open System Settings → Privacy & Security, scroll to the bottom, and click Open Anyway next to the blocked-app notice.
  3. Confirm the build is properly signed: codesign -dv /Applications/Agentum.app should print an Apple Developer ID team identifier without errors.
  4. If the bundle isn’t notarized (Gatekeeper says “not notarized”), you grabbed an unofficial build — re-download from https://theagentum.com/downloads/.
  5. Still blocked? Email support@theagentum.com with the macOS version.

Symptom: Reinstalling Agentum — what data survives, what doesn’t

Reinstalling the .app bundle does not touch user data. Specifically:

  1. Survives: anything under ~/Library/Application Support/YuriClaw/ — your license.json, settings.json, tunnel/, and the rest of userData. The data dir is pinned to YuriClaw via app.setPath even though the product is now called Agentum.
  2. Survives: ~/Documents/YuristicPlugs/ (your agents and configs) and ~/Library/Application Support/YuriClaw/yuriclaw-data/ (host volumes for the container stack).
  3. Replaced: the bundle at /Applications/Agentum.app itself, plus its bundled resources (license-verify-key.pem, the cloudflared binary, the bundled docker-compose).
  4. Lost: anything you stored only inside a container’s writable layer (rare; the stack uses host volumes for everything that matters).
  5. If you want a true clean slate, remove ~/Library/Application Support/YuriClaw/ before reinstalling — but you will lose your license cache and have to reactivate. Email support@theagentum.com if reactivation fails after a clean install.

Network / Telegram Mini App issues

Symptom: TMA tunnel won’t start

cloudflared is supposed to spawn after the wizard’s tunnel:onboard IPC completes. If it never reaches the registered state, traffic can’t reach your listener.

  1. In System → Settings → Remote Access, check the status pill. If it says “Starting…” for more than 30 seconds, click Stop then Start again.
  2. Open Console.app and filter for [tunnel]. Look for tunnel: spawning cloudflared followed by Registered tunnel connection — multiple “registered” lines are expected (4 redundant edge connections).
  3. If you see error="..." lines, your network is blocking outbound 443 to Cloudflare’s edge. Try a different network.
  4. Run cloudflared manually for a verbose log: /Applications/Agentum.app/Contents/Resources/runtime/cloudflared tunnel --config "$HOME/Library/Application Support/YuriClaw/tunnel/config.yml" --loglevel debug run <tunnel-id>. (The tunnel ID is in config.yml.)
  5. Still failing? Email support@theagentum.com with the cloudflared log output.

Symptom: The Mini App URL gives “522” or “1033” Cloudflare errors

The tunnel is registered with Cloudflare but the origin (your listener) isn’t reachable from the tunnel.

  1. From your terminal: curl -i http://127.0.0.1:18803/tma/. Expect 200 OK. If you get Connection refused, the listener isn’t running — see the next symptom.
  2. From inside the container: cd ~/Library/Application Support/YuriClaw/yuriclaw-data && docker compose exec agent curl -i http://127.0.0.1:18803/tma/. If the host curl works but in-container doesn’t, the listener is bound to the wrong interface.
  3. Confirm the listener binds to 0.0.0.0 not 127.0.0.1: docker compose exec agent ss -tlnp | grep 18803 should show 0.0.0.0:18803. If it shows 127.0.0.1:18803, you’re on a build older than PR #99 — update Agentum.
  4. Confirm the compose mapping is intact: grep '18803' ~/Library/Application Support/YuriClaw/yuriclaw-data/docker-compose.yml should show - "127.0.0.1:18803:18803".
  5. Still broken? Email support@theagentum.com with the tunnel hostname and the curl outputs.

Symptom: “Sign in” inside the TMA fails

Every /api/tma/* request requires a valid X-Telegram-Init-Data header. If auth fails, the bot token is wrong or the init data has expired.

  1. Close the Mini App on your phone and re-launch it from the bot’s menu button. Telegram regenerates initData on every launch (5-min validity for writes, 1h for reads).
  2. If 401s persist after a fresh launch, the bot token in System → Settings → Telegram Mini App doesn’t match the bot you’re talking to. Re-paste the token from @BotFather, Save, Restart agent.
  3. Confirm your numeric user ID is in Allowed User IDs — a missing ID returns 401 even with valid initData.
  4. Don’t try to test from a desktop browser — browsers can’t construct valid initData (they don’t have the bot token), so direct browser visits always 401. Use Telegram on your phone.
  5. Still broken? Email support@theagentum.com with the bot’s @username.

See also