Troubleshooting

Something not working as expected? This page collects the most common issues across PebbleChat, PebbleFlows, PebbleObserve, and organisation admin — with pointers to where to look in the UI and where to get help when this page isn’t enough.

The fastest way to get help

Use the in-app feedback modal. Every page in PebbleAI has a Help menu in the top bar (question-mark icon). Open it and click Submit Feedback. You get:

• A draggable, screenshot-aware dialog you can reposition while you point at the thing that’s broken
• Up to five screenshots attached to one submission — captured, pasted, or uploaded
• Direct delivery to the engineering team’s Jira queue, with your organisation context captured automatically
• A draft that’s preserved for the rest of your browser session, so you won’t lose what you typed if you close the dialog by accident

This channel is much faster and more actionable than email, because it lands directly in the tool engineers already use to track bugs. Always include a screenshot — it saves a round trip of “can you show me what you’re seeing?”.

For full details of the feedback flow see Help Menu & Feedback.

Check the status page first

Before digging into a suspected problem, check whether PebbleAI itself is having an incident:

Status page: pebbleai.statuspage.io

If there’s an active incident listed, the thing you’re seeing is probably a symptom of that — wait for resolution or watch for updates rather than filing a new report.

PebbleChat issues

”No Models Available” in the model selector

Walk through this in order:

1. Check your organisation has shared models. Go to User Settings → Models — if the page is empty, your org admin hasn’t enabled any models yet. Ask them to enable models at Admin → Models.
2. Check you’ve enabled a model for your account. Even when your org has shared models, you need to click Enable Model at User Settings → Models to have them appear in your composer.
3. Check the underlying credential is still valid. An expired AWS key, a deleted OpenAI API key, or a revoked OAuth token will make every model in that provider unusable. Admins can check Admin → Credentials.
4. Hard-refresh your browser. Occasionally the model list is cached.

PebbleChat responses are very slow

1. Check which model is being used. Large reasoning models (Claude Opus with extended thinking, o1, o3) take noticeably longer than smaller models. If Auto is consistently routing to a slow model, talk to your admin about tuning PebbleRouter.
2. Check the context window indicator. A near-full context window means every message carries more data, which slows things down. Compression should kick in automatically — if it’s not, check Admin → Configuration → Chat Settings.
3. Check for active research. The Research & Tools activity stream shows every tool call and web search. A slow response is often explained by ten seconds of tool calls; expand the stream to see.
4. Check the status page. Latency incidents affecting the underlying providers will be listed.

A background chat got stuck or never completed

1. Click the conversation in the sidebar — the spinner should either still be active or the run should have failed with a visible error.
2. Check the activity stream for any error status chips. Errors are usually credential-related (expired token, rate limit) or tool-related (external service unavailable).
3. Send a follow-up message to retry — the existing conversation context is preserved.
4. If the spinner has been there for more than 10 minutes, the server-side timeout may have fired and the chat is stuck. Stop it manually and start a new one.
5. File a feedback report with a screenshot of the stuck conversation if the issue repeats.

The activity stream is missing sources or claims I didn’t trigger a search

1. Expand the Research & Tools panel to see exactly what happened. If there are fewer steps than you expected, PebbleChat may have answered from its training data without running tools.
2. Check whether web search was enabled — the web-search toggle on the composer might be off.
3. Ask the same question again with a more explicit trigger: “Search the web for…” or “Using current sources…”
4. Report the response via Submit Feedback with a screenshot if you think PebbleChat should have searched but didn’t.

A specific @mention or asset discovery isn’t finding the right thing

1. Check the asset is shared with you. An asset owner may have made it private. Ask them to share it with your workspace or organisation via the sharing dialog — see Asset Sharing.
2. Check the asset is marked discoverable. Asset discovery only finds assets with the Discoverable toggle on. The owner sets this in the asset’s Discovery configuration.
3. Check the description quality. Asset discovery uses the description field for embedding-based matching. A vague description (“HR bot”) won’t match as well as a specific one (“Searches the company HR handbook for questions about leave, benefits, expenses, and policies”).
4. @mention it explicitly instead if discovery isn’t working — that always overrides the discovery system.

Files I uploaded aren’t being used in the response

1. Check the file type is supported. See File Attachments for the full list.
2. Check the file size. Very large files may be truncated to fit the context window.
3. Check the context indicator. If the context is already near-full, newly attached files may be pushed out by compression. Start a fresh chat for very large documents.
4. Reference the file explicitly in your prompt — “Using the attached file, summarise…” — rather than relying on implicit use.

PebbleFlows issues

A chatflow / agentflow fails when I run it

1. Check the execution trace — PebbleFlows shows the node where execution stopped and the error message. Most failures are visible right there.
2. Check the underlying credential — the most common cause is an expired or invalid credential on a model, tool, or document-store node.
3. Check PebbleObserve → Logs — the full request log includes the model provider’s error message, which is often more specific than what PebbleFlows surfaces.
4. Run the flow in debug mode if your install supports it, to step through the nodes one at a time.

A flow works in the builder but fails when called via API

1. Check the API key — you need a valid User Settings → API Keys key, not your PebbleAI login.
2. Check the flow ID in your API call matches the published flow.
3. Check the flow is saved — the builder runs against the in-memory draft, but the API calls the last saved version.
4. Check the request body format — the PebbleFlows API Reference shows the exact shape.

Document store retrieval is returning wrong / irrelevant results

1. Re-index the store after significant content changes — the vector index may be stale.
2. Check chunk size — too-small chunks lose context, too-large chunks dilute relevance. The optimal size depends on your content.
3. Check the embedding model — an inappropriate embedding model (e.g. a small English-only model for multilingual content) degrades retrieval.
4. Improve the discoverable description — if the issue is with asset discovery pulling in the wrong document store, the description is usually the cause.

PebbleObserve issues

Traces aren’t appearing

Traces are automatic in PebbleAI — if nothing is showing up in Admin → PebbleObserve → Logs, something more fundamental is wrong.

1. Check the time range filter. Default is usually “Last 24 Hours” — if you’re looking for older activity, widen the range.
2. Check any other filters — model, user, status code filters can hide the rows you expect.
3. Click Reset Filters to start clean.
4. Check that the PebbleObserve service is healthy — if the status page shows an incident, traces may be delayed.

Usage dashboard numbers don’t match what finance expects

1. Check you’re looking at the right time range — the dashboard defaults to the last 7 days.
2. Check the currency — costs are typically displayed in USD based on provider pricing, not your local currency.
3. Export the underlying data via the Export button and cross-check against your provider bill.
4. Cost estimates can drift slightly from the provider bill because of how provider discounts, credits, and rounding are applied — differences of a few percent are normal.

Organisation Admin issues

Invited users aren’t receiving emails

1. Check your SMTP configuration at Admin → Configuration → Email — bad SMTP settings are the #1 cause of missed invites.
2. Send yourself a test invite to an email you control to verify delivery.
3. Check the user’s spam folder — corporate filters can quarantine PebbleAI invites on first contact.
4. Use the password-set invitation flow as a fallback — type a password directly in the Invite dialog and the user is created immediately with no email. Communicate the password out-of-band. See User Management.

A new model isn’t appearing for users even after I enabled it

1. Check you saved the change in Admin → Models — a common miss.
2. Check the sharing scope — Pebble Router only models don’t appear in user selectors, only in routing profiles. If you wanted it user-visible, change the scope to Organization or Workspace.
3. Ask the user to refresh and check User Settings → Models — they still need to self-enable the model in their personal selector.
4. Check the credential — an invalid credential can prevent a model from being offered to users.

SSO stopped working after I changed something

1. Check Admin → Login Activity — look at the most recent SSO attempts and read the Message column. The failure reason is usually there.
2. Check the OAuth callback URL at Admin → Configuration → OAuth — the URL configured in your identity provider must match PebbleAI’s callback exactly.
3. Check the SSO Config tab — if you recently rotated a client secret, it must also be updated here.
4. Use the “Reset OAuth Registration” action at Admin → Configuration → OAuth if the stored registration is corrupted.

Voice issues

The microphone button does nothing

1. Check your browser has microphone permission for demo.pebblecloud.io (or your install’s domain).
2. Check voice is enabled for your organisation at Admin → Configuration → Voice Settings. If the admin hasn’t picked STT and TTS models, voice is inactive.
3. Check your microphone itself is working — test it in your OS sound settings before blaming PebbleAI.
4. Reload the page — the LiveKit connection is established on page load; a stale connection can block audio.

Voice transcription is inaccurate

1. Speak a bit more slowly and clearly — streaming STT works best with steady pace, not rapid-fire delivery.
2. Check the STT model configured by your admin — some STT models are tuned for different accents and domains.
3. Check background noise — LiveKit’s VAD (voice activity detection) can struggle in loud environments.

When this page doesn’t have your answer

If you’ve worked through the relevant section above and your issue is still there:

1. pebbleai.statuspage.io — check for active incidents first
2. Help menu → Submit Feedback — the fastest way to get your issue seen by engineering. Always include a screenshot.
3. Ask your organisation admin — many issues (permissions, credentials, provisioned models) need admin action
4. Contact PebbleAI support via your organisation’s agreed support channel

The feedback modal is usually the right first stop, because it captures all the context the engineering team needs in one go — your organisation, the URL you were on, and any screenshots you attach.