Troubleshooting

"My microphone isn't working in the embed"

The most common cause is a missing allow attribute on the iframe. Make sure your embed code includes:

Without this, the browser blocks microphone access inside iframes. Also ensure the page is served over HTTPS — browsers don't allow microphone access on insecure pages.

"The voice sounds robotic or unnatural"

Try switching to a different voice from the sidekick detail page. Cartesia Sonic voices tend to sound the most natural for conversational use. You can preview voices before selecting. If you're using BYOK, make sure your TTS API key is valid and your account has sufficient credits.

"There's a long delay before the sidekick responds"

Response latency depends on the LLM provider. For voice conversations, we recommend Cerebras or Groq for the lowest latency. If you're using OpenAI or Anthropic, responses may take slightly longer because these models prioritize depth over speed. If using Sidekick Forge Inference, the optimized defaults are already configured for lowest latency.

"The sidekick interrupts me while I'm still talking"

Turn detection is handled by the speech-to-text model. In noisy environments, background sounds can be misinterpreted as speech endings. Try using a headset or moving to a quieter space. The system also adapts over the course of a conversation.

"The embed shows a blank page or loading spinner"

Check that your embed URL is correct. The format is: https://sidekickforge.com/embed/{client_id}/{sidekick_slug}. Verify both the client ID and slug match what's shown on your sidekick detail page. Also check that the sidekick is enabled (not disabled).

"The embed doesn't load on my WordPress site"

If you're using the Sidekick Forge Connect plugin, make sure your API credentials are entered in the plugin settings and the bridge auth is working. Check Settings → Sidekick Forge Connect in your WordPress admin. If using a raw iframe, ensure your hosting allows iframes and the X-Frame-Options header isn't blocking the embed.

"The chat looks cut off or too small on mobile"

The embed is fully responsive, but it needs a minimum height to display properly. Set min-height: 600px on the iframe or container. For voice mode, we recommend at least 600px height. See the Embedding guide for recommended sizes by mode.

"My document is stuck on 'Processing'"

Large documents (especially PDFs with many pages) can take several minutes to process. If a document has been processing for more than 10 minutes, try deleting it and re-uploading. Make sure the file isn't corrupted and is within your plan's size limits (5MB for Adventurer, 50MB for Champion).

"My sidekick ignores my uploaded documents"

First, confirm the document status is "Indexed" (not "Processing"). Then check that the document is assigned to the correct sidekick — by default documents are available to all sidekicks, but if you've restricted access, the sidekick may not see it. Finally, try asking the question using similar language to what appears in the document. See the Knowledge Base Guide for more tips.

"Citations link to the wrong document"

This usually happens when multiple documents cover overlapping topics. The system retrieves the most semantically similar chunks, which may come from an unexpected document. Consolidate overlapping content into a single authoritative source, or restrict document access per sidekick.

"My sidekick gives answers that are too long / too short"

This is controlled by the system prompt. Add explicit length guidance: "Keep responses under 3 sentences unless the user asks for more detail" or "Provide thorough, detailed explanations with examples." The system prompt is the most effective way to control response length and style.

"My sidekick answers questions it shouldn't"

Set clear boundaries in the system prompt. For example: "You only answer questions about our products and services. For personal advice, legal questions, or medical questions, politely explain that you can't help with those topics and suggest they consult a professional."

"My sidekick makes up information"

This is called "hallucination" and happens when the AI doesn't have enough context to answer accurately. Two solutions: (1) Upload more relevant documents to the Knowledge Base so the sidekick has real information to reference. (2) Add a system prompt instruction like: "If you don't have enough information to answer accurately, say so honestly rather than guessing."

"I can't log into the admin panel"

Make sure you're using the correct URL for your environment. If you've forgotten your password, use the password reset link on the login page. If your account was recently created, check your email for a confirmation link.

"I'm seeing 'limit exceeded' but I just upgraded"

After upgrading, it may take a few minutes for the new limits to propagate. If you're still seeing the warning after 15 minutes, try logging out and back in. Your usage counter may also need to reset at the start of the next billing period.