Troubleshooting

Start with tag doctor (or tag NAME doctor for one Tag). It groups checks into runtime, configuration, memory, agent, and Slack, and shows a fix for each failed check. In the Tag app, open the Tag's Logs tab; Copy full log copies every line.

flowchart TD
    Problem["Something's wrong"] --> Where{"Where?"}
    Where -->|Installing| Install["Installing Tag"]
    Where -->|App| App["Tag app"]
    Where -->|After an upgrade| Upgrade["After an upgrade"]
    Where -->|Slack request| Doctor["tag NAME doctor<br/>then the table below"]

Installing TagCopy Anchor Link

Desktop appCopy Anchor Link

When a Tag can't answer because of its AI connection, AI connections shows which sign-in needs attention. Choose Reconnect next to it.

After an upgradeCopy Anchor Link

Tag applies upgrade migrations on the first start after an upgrade. They need no setup, and a failed one is retried on the next start.

Running TagsCopy Anchor Link

Failed Slack requestsCopy Anchor Link

When a backend request fails, Tag shows the requester an evidence-based cause, an error reference, and recovery actions in a private Slack message. If Tag doesn't recognize the failure, it shows the backend's own error message, with credentials redacted. A timeout does not by itself mean that the network failed. Retrying creates a new reference and keeps the earlier attempt linked in the local report.

Report issue opens a private preview for the authorized person who made the request. The preview contains an allowlisted report with the Tag version, backend identity when available, failed stage, recognized cause, bounded diagnostics, and later health-check timestamps. It does not include tokens, conversation text, file contents, or raw logs by default. Add context only after reviewing it. Slack does not provide a clipboard button for this surface, so select the report text manually. Nothing is posted automatically.

To share a report, select the reviewed text, join Hover Community, and paste it into the discussion. GitHub Issues remain the canonical record for confirmed bugs; community posting is a manual first-release handoff. Reports are stored in the selected Tag's private state for up to 30 days, bounded to 50 records, and an expired or unavailable reference is not treated as authorization to read anything.

Fix with coding agent posts a short, copyable prompt with the sanitized diagnostic report in a message only the requester can see. In a direct message, the prompt stays in that private conversation. Give it to an agent with access to the machine running Tag for a local repair. The separate Report issue action provides a private report preview for manual sharing. See When a request fails for the full action, report, and retention details.

When reporting a problem, include the Tag version (tag version), operating system, AI backend, failing check, and a redacted log excerpt. Never include tokens.

Slack indexing is rate-limitedCopy Anchor Link

Tag-managed memory honors Slack's HTTP 429 Retry-After delay, shares the cooldown across channels in the same workspace, and retries the current API request without restarting the channel's in-progress history read. Channel listings are cached for up to a minute so readiness checks do not repeatedly consume Slack's discovery quota.

During a cooldown, tag status shows Indexing paused by Slack with the retry delay. tag start doesn't wait for it: the Tag connects and answers, and indexing continues in the background. History search covers each channel once it is indexed. Repeating setup or restarting memory does not clear Slack's limit. A memory restart preserves the cooldown, but may require replaying an interrupted indexing task.

Existing Tag-managed memory processes automatically migrate to the rate-aware runtime on the next start. Tag verifies process identity before restarting memory and verifies the new runtime and HTTP health before recording the migration. This briefly interrupts shared memory for other running Tags; stored indexes, connector configuration, and credentials are preserved. Independently managed or remote MFS servers require an equivalent connector update by their operator; Tag does not replace their runtime.