FAQ & Troubleshooting
Answers to the things people ask most, and what to do when a screen doesn’t look the way you expect. About 7 minutes.
KeyOne is honest about its own state, which means you’ll sometimes see a “Couldn’t load this”, a dash where a number would be, or a notice that written answers are off. Most of the time that’s a status, not a fault. This guide explains the common ones and what to do.
Data & setup
“I’ve signed in but there’s no data yet.”
That’s expected before a warehouse is bound. KeyOne won’t invent numbers to fill the gap. The path to data is: your extracts land in your warehouse → the KeyOne team binds it to the canonical vocabulary → the scheduled runs compute KPIs and raise decisions → you adopt the products and outlets your data names. See Connecting Your Data.
“How do I connect my own data source from the app?”
Binding a warehouse from inside the app is not a finished feature today. The binding is a configuration file per deployment, written with the KeyOne team; Settings → Sources & binding then shows you what it covers. If you see this described as click-it-yourself anywhere, trust this page instead.
“Products and Customers say some codes have no record — did something break?”
No. KeyOne reads the codes in your bound facts and tells you how many have a master record. Master these adopts the rest in one click, filling in only what the warehouse carries — nothing is guessed. Every code still counts in KPIs whether or not it has been adopted.
Hubs & charts
“A KPI or panel says ‘Couldn’t load this’.”
The query behind it failed — most often the source is unreachable, or a canonical field it needs is unbound. The reason is printed under the notice, and Settings → Sources & binding shows which fields are mapped and whether the source answered a ping. The decisions listed at the bottom of the hub still work: they are read from KeyOne’s own store, not the warehouse.
“A KPI shows a dash instead of a number.”
The query ran and had nothing to measure — zero rows in the window, or a NULL. That is a different fact from a failure, and KeyOne keeps the two apart: a dash with a reason is “nothing to measure”, never a zero pretending to be one.
“A chart’s last point drops off a cliff.”
The current month is still in progress, so a monthly count covers only the days elapsed so far. Panels that do this say so in their caption; the number itself is untouched, because dropping the month would hide real activity and back-filling it would invent some.
Decisions
“Decisions won’t load.”
If the list cannot load, KeyOne says so rather than showing an empty page that reads as “you have nothing to do”. A failure to load and a genuinely empty list are different states and are shown differently. See Notifications.
“Why is a low-value item near the top?”
The list is ranked by each decision’s number, highest first, and not every number is money: a card measured in days or failed checks (“41 days”, “74 checks”) ranks by that count. Check the unit printed beside the figure before reading it as rand. Severity does not change the order — it is shown as a badge so you can filter on it. See Understanding a Decision’s Value.
“Should I trust the exact number on a decision?”
It is a direct measurement from your data at the moment of detection, in the unit the rule declares — not a model’s estimate, so there is no range or confidence score to read. Treat it as a prioritisation tool, not a promise: open Show the data behind this card to see the rows and the query it came from, and let the verification loop say afterwards whether acting helped. See Understanding a Decision’s Value.
Visibility & access
“I can’t see a store / product / hub I expected.”
KeyOne only ever shows you what your account is permitted to see — your access scope bounds your hubs, KeyChat answers, and work items. If something’s missing, it’s usually a scope or role matter for your administrator, not a bug. See Account & Settings.
“Why does KeyChat refuse a question or give a limited answer?”
Two possibilities. First, KeyChat runs under your scope and won’t show data you’re not entitled to. Second, if no analyst provider is configured for your deployment, written answers are off and the rail says so — drill-downs opened from a chart, table or decision still work, because those read your data directly and never went through a model. KeyChat won’t fabricate an answer in either case. See KeyChat.
KeyLink (field)
“My route order looks odd.”
KeyLink optimises visit order using straight-line distances, not real road distances or live traffic, and the map is an overview rather than turn-by-turn navigation. It’s a useful running order — adjust with local knowledge where roads or one-ways make a difference. See KeyLink for Field Reps.
“The shelf audit results — are they real?”
The shelf-photo analysis is currently simulated. The photo capture, the write-back, and automatic task creation are real and working; the part that identifies what’s in the photo is a placeholder, and results are labelled as simulated so you’re never misled. When the real recognition model is enabled, it slots into the same workflow.
“I lost signal mid-visit — did I lose my work?”
No. KeyLink shows an offline banner and keeps working; your changes sync automatically when you reconnect. Watch the pending-sync badge in the top bar.
Account & security
“How do I change my name, email, or password?”
- Display name: not available in-app. There is no Account tab and no profile-editing route — contact your administrator or the KeyOne team.
- Password (signed in): not available in-app. Use Forgot password? on the sign-in screen, or contact the KeyOne team.
- Password (forgotten): Use Forgot password? on the sign-in screen — the link expires in 24 hours.
- Email: Not available in-app yet — contact the KeyOne team.
“How do I add or remove a teammate?”
Go to Settings → Users (you need the admin role to see the management controls). From there you can invite by email, change a member’s role, or remove them. If you don’t have that role, ask your administrator.
Still stuck?
- Email: support@keyone.sh
- Response time: within 1 business day (SAST)
When you write in, it helps to include what you were doing, what you expected, and the exact wording of any on-screen message — the messages are designed to be precise about what’s going on.