Diagnosing a problem

Summary#

This is the order to work in when a customer reports that something is broken. It starts with the six facts that make a report diagnosable, then walks the admin console from the narrowest view to the widest: this customer, this run, this tool, the whole platform. Following it in order usually identifies the cause in under five minutes, and it always produces a ticket an engineer can act on without going back to the customer.

Purpose#

Most support time is lost in two places: asking the customer for information you should have requested up front, and checking screens in an order that hides the answer. A customer who says "the tool is broken" may be describing a plan gate, an empty data result, a stale cached answer, a configuration gap, or a genuine failure. Those five have completely different owners and completely different fixes. Working outward from the individual account tells you which one you have before you spend anyone's time.

Requirements#

• Access to the admin console with an active admin account.
• The customer's account email address, exactly as they sign in with it.
• A reproducible description of what they did, not a summary of what they concluded.

Permissions#

Two admin roles exist.

If a screen shows data but a button does nothing, you are an admin on an owner-only action. Ask an owner rather than retrying. Every mutation, whoever makes it, is written to the audit log with the actor, the action and the target. See Getting admin access and Roles and what each can do.

Navigation Path#

Admin console → Operations → Customers

The console groups its screens as Main (Dashboard, Subscribers, Messages, Bug Reports, Workflow Failures), Operations (System Health, Admins, Config, Tools & Cache, Customers, Blog Moderation, Run Log, Jobs) and Account (Email Inbox, Usage & Activity). See Admin console tour.

Step-by-Step Guide#

1. Collect these before you open anything#

Ask for all of it in one reply. A partial report costs a round trip.

Also worth asking when relevant: which browser and operating system; whether they were in their own workspace or a teammate's; which interface language was selected; whether a share link, export or scheduled report was involved; and whether they had just changed plan.

2. Look up the customer#

Go to Admin console → Operations → Customers, enter the email and click Load. Read the whole screen before forming a theory.

• Plan tile: the plan currently applied, and a red suspended badge if the account is suspended. A suspended account is refused at every paid gate with This account is suspended. Please contact support.
• Used this month: used against quota, and how much remains. If used has reached quota, the report is a credits question, not a fault. See I ran out of credits.
• Breakdown: AI runs and tool runs for the month key shown.
• Billing card: what the payment provider actually says, including subscription status, tier, amount and renewal date, plus whether the plan was set by the payment provider, by an administrator, or is the default. This is the screen that settles "I paid and nothing changed". See My plan did not update after paying.
• Connected channels: their social connections, with a revoke control.
• Team members: seats used against the plan's cap, and whether they are over it.
• Recent actions on this customer: the audit trail filtered to this address. Check it before changing anything, in case a colleague already did.

See Customer lookup and billing.

3. Find the run#

Go to Admin console → Operations → Run Log. Filter by the customer's email, set status to Failed, and search the tool name. Each row shows when, which customer, which tool or action, and the status.

If the run is not there at all, the request never reached the platform. Suspect a signed-out session, a browser extension, a corporate proxy, or a stale tab. If it is there and marked Success, the customer is describing an empty or unexpected result rather than a failure. See A tool returned no data.

Export CSV is available if you need to attach the sequence to a ticket. See Run inspection.

4. Decide whether it is one customer or the tool#

Go to Admin console → Operations → System Health and set the range to the last 24 hours.

1. Read the Error rate tile. A platform problem moves it; one customer's bad input does not.
2. Find the tool in the Tool health table. Its badge is healthy, degraded, down or idle. degraded and down mean stop investigating the customer and start investigating the tool.
3. Read Grouped issues underneath. Issues are grouped by their normalised message, so a repeated failure appears once with a count and a last-seen time. Hover the issue cell to see a real sample. Resolve an issue once it is genuinely fixed; a new occurrence reopens it automatically as a regression.

See Error log and resolution and Metrics and usage analytics.

5. If it was a multi-step workflow, check Workflow Failures#

Go to Admin console → Main → Workflow Failures. Multi-tool workflows report each step that hangs, errors or returns nothing. Filter to Open only, and read Most Failing Steps first: a single step failing across many customers is a different problem from one customer's workflow failing at random points. Each card shows the step, the seed input, the error text, the workflow, the user and whether it timed out. Mark it resolved once fixed.

6. If anything scheduled is involved, check the Job Console#

Go to Admin console → Operations → Jobs. Each job shows a status chip (Scheduled, Due now or Disabled), its last run, its next run and how many items it has. Two readings matter:

• Everything stuck at Due now with frozen last-run times means the external scheduler is not reaching the platform. That is an internal-secret or deployment problem, not a customer problem. See 503 and service-unavailable errors.
• A job running normally while a customer's schedule never fires is a customer-level question. See My scheduled report never arrived.

Owners can press Run due now, which triggers the job immediately but still processes only items that are actually due. It is not a forced re-run. See Background jobs console.

7. Check whether configuration explains it#

Go to Admin console → Operations → Config.

An undocumented tool_off: row is the most common cause of "this tool broke for everyone overnight". See Runtime configuration.

8. If the complaint is stale data, check the cache#

Go to Admin console → Operations → Tools & Cache. Find the tool and read Cached for. A tool with a long lifetime returns the same answer to everybody until it expires, which is correct behavior and saves provider cost, but it looks like a bug to a customer who just changed their site.

Two remedies, in increasing order of cost:

1. Tell the customer to use the tool's own fresh-run path. Reopening saved work is free; running fresh spends credits and fetches new data.
2. Owners can clear the cache for that one tool. The next runs fetch fresh data at full provider cost, for everyone.

See Tools and cache management and Result caching and freshness.

9. Check who changed what#

Go to Admin console → Operations → System Health and scroll to Recent admin actions, or filter the audit log by actor or action. Every administrative mutation is recorded with a timestamp, the actor, the action and the target. If a customer's plan or usage changed unexpectedly, this screen says who did it. See Audit log.

10. Escalate with a complete ticket#

Escalate when the tool is down or degraded platform-wide, when a not-configured message names a missing dependency, when the Job Console shows the scheduler is not arriving, or when a failure reproduces with valid input on a healthy account.

Include, in this order:

1. The customer's email and current plan.
2. The exact message, quoted.
3. The tool and the exact input.
4. The timestamp of the failing run from the Run Log.
5. Whether the tool is healthy, degraded or down, and the current error rate.
6. The grouped issue text and count, if one matched.
7. What you already ruled out: plan gate, credits, suspension, cache, configuration switch.

Troubleshooting#

FAQs#

What should I check first when I have almost nothing to go on? The Customers screen. Plan, usage, suspension state and billing truth explain more reports than any other single view, and they take fifteen seconds to read.

How do I tell a plan gate from a real failure? Read the message. Gates say what they need and name a plan or a quota. Failures say something went wrong. Every gate message is listed in Error message reference.

Can I see what the customer saw? Not directly. The console shows what the platform did, not the customer's screen. That is why the exact message text is worth insisting on.

A customer says their data is out of date. Is that a bug? Usually not. Results are cached for a defined period per tool so the same question does not re-bill a data provider. Check the tool's cache lifetime before treating freshness as a defect.

Is it safe to reset a customer's usage or refund credits? Yes, and both are audited. Owner-only. Reset clears the month's counter; refund adds a specific number of credits back. Record the reason in the ticket, because the audit log stores the action but not your reasoning.

Should I ever suspend an account during a support call? No. Suspension blocks every paid gate immediately and is an account-management action, not a diagnostic one.

What if the admin console itself is showing errors? Treat that as a platform incident. Check whether the failures are configuration messages naming a missing dependency, which points at 503 and service-unavailable errors, and escalate rather than working through customers individually.