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 “not provisioned” or “degraded” message. 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 your first feed is matched. KeyOne won’t invent numbers to fill the gap. The path to data is: a feed is brought in → products and stores are matched → metrics compute → (with the analytics engine provisioned) hubs populate and decisions appear. See Connecting Your Data.
“How do I connect my own data source from the app?”
Self-service, click-it-yourself data connection is not a finished feature today. Getting a feed in is arranged with the KeyOne team using standard extract templates. If you see this described as fully automated anywhere, trust this page instead: it’s assisted, not yet self-serve.
“Some products or stores were flagged for review — did something break?”
No. When a feed lands, KeyOne auto-matches what it can and flags anything ambiguous or new for a person to confirm rather than guessing. Confirm the flagged items and they flow into metrics. Acting on unmatched data is disabled by design.
Hubs & charts
“A hub shows ‘not provisioned’.”
The hub’s live KPIs and charts are rendered by KeyOne’s embedded analytics engine. If that engine isn’t configured in your environment, the hub says so plainly instead of showing blank or fake charts. The Decisions & Actions panel at the bottom of the hub still works — you can keep triaging and resolving items. Charts appear once the engine is connected. See Using a Hub.
“A hub says ‘degraded’ or ‘sidecar unavailable’.”
The analytics engine is configured but temporarily unreachable. This is a transient state — analytics restore automatically when it reconnects. Nothing for you to fix; the message is just being honest that the charts you’d normally see aren’t live this moment.
“The charts in the docs look different from my app.”
The Using a Hub guide shows an illustration of the layout, not a screen capture. A hub’s real charts are generated live against your data and can’t be honestly screenshotted until the engine is provisioned — so we show a worked illustration of where everything sits. Your live hub will render real data in those positions.
The Work Queue & decisions
“The Work Queue won’t load.”
If you see a message like “Work items could not load”, the backend that serves work items isn’t wired up in your environment yet. It’s labelled as a placeholder rather than left blank. Once the connection is live, your queue populates. See Decision Inbox & Win List.
“The Win List is empty or unavailable.”
The Win List is produced by the engine’s nightly ranking. If it shows “Win List unavailable — engine not connected,” the engine isn’t connected yet in your environment. The rest of the Work Queue still works.
“Why is a low-value item near the top?”
Two reasons: Critical and Blocked items bubble to the top regardless of value, and within a type-group items sort by value. If something looks mis-ranked, check whether it’s flagged Critical. See Decision Inbox & Win List.
“Should I trust an estimate’s exact number?”
Treat impact estimates as a prioritisation tool, not a promise. Read the P10–P90 range and the confidence, and open “Why this estimate?” for the methodology. The T+30 loop checks estimates against reality over time. See Understanding Impact Estimates.
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 the AI engine isn’t provisioned, KeyChat runs in a limited fallback mode and says so with a banner — full, tool-using answers arrive once the engine is connected. KeyChat won’t fabricate a figure to fill a gap. 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
“Where do I set up two-factor authentication (2FA)?”
The 2FA enrolment UI is not yet wired in the app — the backend TOTP APIs are built and ready, but the in-app setup flow hasn’t shipped yet. Settings → Security shows an honest “Not yet available” badge. When it ships, you’ll enrol there. See Account & Settings.
“How do I change my name, email, or password?”
- Display name: Settings → Account → Display name → edit → save. This works today.
- Password (signed in): Settings → Security → Change password. This works today.
- Password (forgotten): Use Forgot password? on the sign-in screen — the link expires in one hour.
- Email: Not available in-app yet — contact the KeyOne team.
“How do I add or remove a teammate?”
Go to Settings → Members (you need an Owner or 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 org owner or 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.