Troubleshooting

Start with the smallest reversible check. A factory reset erases local user state and should not be the first response to a connection or provider problem.

First: identify which layer is failing

Ask these questions in order:

1. Can I open the local console? If not, start with network access.
2. Does Overview show the Agent running? If not, restart the agent or services.
3. Is a model provider configured and valid? Test or re-authenticate it.
4. Is a chat channel connected? Recheck its token/account and delivery path.
5. Is the failure limited to Browser, a schedule, or one tool? Repair only that component.

The Overview page shows device details, Agent status, Browser status, the active provider, and basic restart actions.

I cannot open the local console

1. Confirm MangoTart has power and Ethernet is connected to a LAN port on the router.
2. Wait about one minute after boot.
3. Put your phone/computer on the same LAN; turn off mobile data temporarily if it keeps bypassing Wi-Fi.
4. Open the exact label hostname, such as http://mango-abc-def.local.
5. Try the Find your MangoTart page with the MT-XXXXXXXX code.
6. Check that the router is not using a guest network, client isolation, separate VLAN, or firewall rule between the two devices.
7. Temporarily disable a VPN or private-relay feature that blocks local addresses.

The find page returns a private LAN address; it cannot make the console work from outside the home network. See Network and access for more detail.

The console opens, but the agent does not reply

On Overview, check the readiness items:

• Agent is running — if stopped, use Restart Agent.
• Model provider set — if missing, configure one under Model provider.
• Chat platform connected — if missing or uncertain, reconnect it under Messaging.

If all three look healthy:

1. Send a short plain-text message rather than retrying the failed complex task.
2. Check whether the model provider is reachable and funded.
3. Restart the Agent once and wait for it to return online.
4. Try from the configured direct chat instead of a group to rule out group/session routing.

Model login or API key fails

Open Model provider and use Test connection where available.

• OAuth/ChatGPT login expired — choose Re-authenticate and complete the device-code flow again.
• Authentication failed — replace the API key and make sure it belongs to the selected provider.
• Model unavailable/not found — choose a model shown for your account or enter the exact supported model ID.
• Insufficient balance/rate limit — resolve it in the provider's own dashboard.
• Custom endpoint fails — verify the base URL, model ID, API key, TLS, and OpenAI-compatible behavior.
• Mainland China — OpenAI login/inference endpoints are not normally reachable; choose a reachable provider. MangoTart does not proxy the connection.

After a provider change, restart the Agent if the console asks you to apply it. See Models and ongoing costs.

A messaging channel does not work

• Recheck the bot token, account ID, user ID, or QR login required by that channel.
• Confirm you are messaging the same bot/account configured on MangoTart.
• Save the channel and restart the Agent when prompted.
• For Telegram/Discord allow-lists, confirm your user ID—not your username—was entered.
• For a group chat, confirm the bot is in the group and the platform allows it to read the required messages.
• Check whether the platform is reachable from MangoTart's network and supported in your region.

Email as a chat channel is different from the Email tool, which lets the agent read and send through your mailbox.

Browser is unavailable or signed out

Open Browser in the console:

1. Check whether the Browser service is running.
2. Use Restart browser service if it is stopped or unresponsive.
3. Open the browser view and sign in again if a website session expired.
4. Test the website manually; changed pages, CAPTCHAs, multi-factor prompts, and anti-bot controls can block automation even when the Browser service is healthy.

Browser profiles and website logins are not included in backups. Re-authentication after restore or migration is expected.

A scheduled task did not run or deliver

Open Schedules and check:

• the task is not paused;
• its next-run time matches the device time zone;
• the Agent, internet, and model provider were available;
• the delivery channel is still connected; and
• the task does not require a browser login or approval that has expired.

Use Run now to separate a schedule problem from a task/provider problem. A task that fails when run now will not be fixed by changing its schedule.

An update fails

MangoTart and Hermes updates run through health checks and return to the previous program version when validation fails. On System:

1. Check the current version and update log.
2. Wait for the automatic maintenance window if the current version is still working.
3. Use the manual update action only when you need it immediately.
4. If the UI reports a failed update and rollback, keep the device powered and connected and contact support with the log and version.

Do not repeatedly power-cycle during an update.

Backup or restore fails

• For cloud backup, confirm internet access and read the last error on System.
• Confirm cloud backup has a password and is enabled.
• For restore, use the password that belonged to that backup date.
• Update the destination so it is not older than the backup source.
• Remember that the import overwrites current memory and settings.
• Download cloud backups from your website device page before unbinding; unbinding permanently deletes them.

See Backup, restore, and migration.

Restart, reboot, or factory reset?

Use the least destructive action:

Factory reset requires an ownership pairing code. It preserves the registered device identity needed for provisioning and support, but returns the user experience to onboarding.

Before contacting support

Gather:

• the MT-XXXXXXXX device code and hostname;
• the approximate time the problem happened;
• the current MangoTart and Hermes versions;
• which page/service is failing;
• the exact error text or a screenshot; and
• the smallest task that reproduces the issue.

Do not send API keys, passwords, backup passwords, or full backup archives by ordinary email. Contact hello@mangot.art. Authorized support has a remote administrative maintenance path; review Privacy, security, and permissions for what that access can expose.