Troubleshooting

If your problem isn't on this page, you're never stuck: get support — join the support room, ask in the community Discord, or email support@ag2.space. A real human will help (and we'll add your fix here so the next person doesn't have to ask).

The app won't open, or my agent seems offline

Your agent runs inside the AG2 Space desktop app — if the app isn't running, the agent isn't either. In order: You can also open the agent terminal and look at the core directly — it is often just waiting at a prompt.

• Launch AG2 Space from Applications (or Spotlight, ⌘+Space). Your agent comes online with it.
• If the app is open but the agent isn't answering DMs, open the Agent Console and check the latest line — it shows what the engine is doing and can restart it.
• If the app crashed, just re-launch it. Queued work picks up where it left off.

Voice says "starting" forever

Almost always one of three things:

• Mic permission: macOS may not have granted AG2 Space access to your microphone. Check System Settings → Privacy & Security → Microphone and toggle AG2 Space on. Then start the voice session again.
• Gemini key missing or rate-limited: if you're bringing your own keys, double-check your Google AI Studio key is pasted in Settings → API Keys. If you're on the managed plan, check your dashboard — voice hours may be exhausted.
• Network: voice opens a WebSocket to Google. Corporate VPN / firewall sometimes blocks it. Toggle the VPN off briefly to confirm.

My Discord / Telegram bot is offline

Most common causes, in order of likelihood:

• Token has a typo. Re-copy from the provider (BotFather / Discord developer portal) and re-paste in AG2 Space Settings. Click Save.
• You forgot to click Save in Settings after pasting. Without that click, the token doesn't persist.
• The bot is on a different Mac. If you've installed AG2 Space on two Macs and both are running, only one can hold a given bot token at a time. The first to start owns the connection.

When the bot is connected, Settings shows a green running badge next to the token field.

A background task seems stuck — my agent isn't replying

The Agent Console is the right place to look — open it and check the latest line. Common states: You can also open the agent terminal and look at the core directly — it is often just waiting at a prompt.

• Still running — long tasks (web research, multi-email drafts, phone calls) can take several minutes. Wait.
• Stalled on a permission prompt — your agent may be waiting for you to approve a file write or app interaction. Respond to the prompt in the console.
• Crashed — restart the engine from the Agent Console. Your queue will pick up where it left off.
• Paused for quota — your agent posts "I'm paused: my Claude usage limit is reached (resets at …)" in your chat and resumes on its own at that time. Switch to a smaller model in Agent settings → Runtime → Model to keep going, or see quota.

I'm getting "quota exhausted" or "rate-limited"

Either provider can throttle:

• Your own Gemini key: free tier has daily request limits. Either wait until the next day's reset, or enable billing on your Google AI Studio project.
• Your own Claude Code: monthly subscription cap — upgrade your plan or wait for the next billing cycle.
• Managed plan: check your dashboard. Top up your wallet or upgrade the tier.

My agent remembered something wrong — how do I fix it?

Memory lives as plain markdown files on your Mac. The simplest fix: tell your agent — say or type "actually, forget that — [correction]" and it updates the relevant memory file, effective on the next request. You can also ask it to show you the memory in question if you want to review what it kept.

Still stuck?

Get support — the support room, the community Discord, or support@ag2.space. Include: macOS version, what you were trying to do, and the latest line in your Agent Console. That's almost always enough to diagnose.