Skip to main content
If your issue isn’t covered here, email support@voxcode.app with a description of the problem, your browser and device, and any error messages you see. We’ll get back to you as soon as possible.
Many state-related issues — stuck UI, audio that won’t play, a preview that won’t load — resolve by refreshing the browser tab. Try a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) before working through the steps below.

​
Voice issues

Voxcode needs microphone access to capture your voice. If the browser blocked the permission or never asked for it, follow these steps:
1

Check the browser permission prompt

When you first click the microphone icon, your browser should show a permission prompt. If you accidentally denied it, you need to reset it manually.
2

Reset microphone permission in Chrome

Click the lock icon (or the camera/microphone icon) in the address bar. Set Microphone to Allow, then reload the page.
3

Reset microphone permission in Edge or Brave

Go to Settings → Site permissions → Microphone and remove the blocked entry for Voxcode. Reload and try again.
4

Check your operating system permissions

On macOS, go to System Settings → Privacy & Security → Microphone and make sure your browser is listed and enabled. On Windows, go to Settings → Privacy → Microphone and confirm browser access is on.
5

Check that no other app is using the mic

Some video call apps (Zoom, Teams) hold an exclusive lock on the microphone. Quit those apps and try again.
If you are accessing Voxcode over HTTP (not HTTPS), the browser will block microphone access entirely. Make sure you are using the secure https:// URL.
Transcription quality depends on your microphone, background noise, and the transcription engine in use.Try these steps:
  • Speak clearly and at a moderate pace. Voxcode uses the Web Speech API on desktop Chrome and Whisper as a fallback on mobile.
  • Reduce background noise. A noisy environment can confuse the silence detector and cut you off early. Move to a quieter space or use a headset.
  • Use a headset or external microphone instead of a built-in laptop mic.
  • Switch to Chrome if you are on Firefox or Safari. Chrome’s Web Speech API implementation is significantly more accurate for English.
  • If you have a strong accent or speak a language other than English, Whisper (the mobile fallback) handles multilingual transcription better than the Web Speech API.
If transcription is consistently wrong for specific technical terms (e.g., framework names, function names), try spelling them out or using text input for those parts.
If you finish speaking but the AI never replies, work through these checks:
1

Confirm the message was sent

Look in the chat for your transcribed message. If it appears but there is no AI reply, the issue is with the AI request, not transcription.
2

Check your credit balance

If your credits are at zero and you are not using a Free-tier model, the request will fail silently. Check your balance in the settings menu and top up or switch to a Free model.
3

Check your internet connection

AI generation requires a live connection to OpenRouter. Verify you are online and not behind a firewall that blocks API calls.
4

Check the browser console for errors

Open DevTools (F12), go to the Console tab, and look for red error messages. A 401 error means an API key issue; a 429 means you are rate-limited; a 500 means a server-side problem.
5

Refresh and retry

A hard refresh clears in-memory state that can cause the AI pipeline to stall. If the issue persists across refreshes, contact support.
Voxcode supports interrupting the AI mid-response by speaking. If your speech is not stopping the AI, check the following:
  • Microphone must remain active — Interruption only works while you are in continuous voice mode (microphone icon is active/lit). If you have stopped the mic, you cannot interrupt.
  • Speak at a clear volume — Voxcode needs to detect your voice above background noise. Quiet speech or whispering may not trigger the interrupt. Speak at a normal conversational volume.
  • Browser audio policy — Some browsers block auto-playing audio until you interact with the page. If the AI’s voice is not playing at all, click anywhere on the page first, then restart voice mode.
  • Check for browser extensions — Ad blockers or privacy extensions can intercept audio APIs. Try in an incognito window with extensions disabled.

​
Preview issues

A blank preview usually means the VFS doesn’t have the right entry-point file, or the project type wasn’t detected correctly.
1

Confirm files were saved to the VFS

Open the file explorer (swipe left on mobile, or click the file icon). Check that your project files — especially index.html for static sites or App.tsx / package.json for React — are present.
2

Ask the AI to regenerate

Say or type: “Save the files and show me a preview.” Voxcode needs the AI to emit code blocks with filenames (e.g., ```html:index.html) to write them to the VFS. A response with code but no filename won’t be saved.
3

Refresh the preview panel

Click the refresh icon inside the preview window. This reloads the preview without resetting your chat session.
4

Hard-refresh the page

If the preview panel itself is stuck, do a full page refresh (Ctrl+Shift+R). Your VFS files are stored in localStorage and will survive the refresh.
React projects run inside Sandpack (an in-browser code execution environment). Common error causes:
  • Missing dependency — If the AI used a package not included in Sandpack’s default bundle, you’ll see a module-not-found error. Ask the AI: “Rewrite this using only standard React, no external libraries.”
  • TypeScript error — Sandpack compiles TypeScript but strict type errors will block rendering. Ask the AI to fix the type errors or switch to .jsx instead of .tsx.
  • Syntax error in generated code — Occasionally the AI produces slightly malformed code. Ask: “Fix the syntax errors in the current code” and Voxcode will regenerate.
  • package.json conflict — If your VFS contains a malformed package.json, Sandpack will fail to initialize. Ask the AI to regenerate a clean package.json.
Check the error message shown in the Sandpack console panel — it usually points to the exact file and line causing the problem.
WebContainer runs Node.js entirely in the browser and has specific requirements:
  • Browser support — WebContainer requires SharedArrayBuffer, which is only available in secure contexts (HTTPS) and in Chrome, Edge, or Brave. It does not work in Firefox or Safari.
  • Secure context required — The page must be loaded over HTTPS for WebContainer to initialize. If you see a security-related error, make sure you are accessing Voxcode at the https:// URL.
  • First boot is slow — On the first load, WebContainer downloads a Node.js runtime. This can take 10–30 seconds on slower connections. Wait for the loading indicator to complete before interacting.
  • package.json must be valid — An invalid or empty package.json will cause the container to fail. Ask the AI to generate a fresh one if needed.
WebContainer does not work behind corporate proxies that block WebSocket connections. If you are on a restricted network, use a static HTML/CSS or React project instead.
If you asked the AI to modify your code but the preview still shows the old version:
  • Check the VFS — Open the file explorer and verify the file was actually updated. The AI must emit a new code block with the filename for changes to save.
  • Click refresh in the preview panel — The preview doesn’t always hot-reload automatically after a VFS write. Click the refresh icon to force a reload.
  • Confirm the AI targeted the right file — If you have multiple files, the AI may have created a new file instead of updating the existing one. Check the file explorer for duplicates.
  • Re-prompt with the filename — If the AI keeps generating code without saving it, say: “Update index.html with the changes.” Specifying the filename explicitly helps the AI write to the correct VFS path.

​
Credits & account issues

Credits are consumed per request based on the number of input and output tokens. Long conversations accumulate context, which increases input token counts over time. A single request on a premium model with a large context window can cost noticeably more than a short one.To reduce credit consumption:
  • Switch to a Free-tier model (Gemini 2.5 Flash, Claude Haiku 4.5, etc.) for exploratory or simple tasks.
  • Start a new conversation to reset context rather than continuing a very long thread.
  • Use fast models for quick questions and reserve premium models for complex generation tasks.
You can view your full usage history in the settings menu to see which requests consumed the most credits. Top up at any time — purchased credits never expire.
BYOK is available on the Premium plan only. If your key isn’t working:
1

Confirm you are on the Premium plan

BYOK is not available on Free or Starter. Check your plan in account settings.
2

Verify the key was saved correctly

Go to Settings → API Keys, remove the existing key, and re-enter it. API keys are encrypted before storage, so a copy-paste error won’t be visible.
3

Test the key directly with your provider

Make a test request directly against OpenRouter or your provider’s API to confirm the key is active and has credits/quota remaining.
4

Check the selected model matches the key's provider

A key from one provider won’t work for a model from a different provider. Make sure the model you have selected is accessible via the key you entered.
If the problem persists, contact support@voxcode.app with your account email and the provider you are trying to use (do not include the key itself).
Voxcode uses OAuth for sign-in. If sign-in fails:
  • Pop-up blocked — Your browser may have blocked the OAuth pop-up. Allow pop-ups for Voxcode’s domain and try again.
  • Cookies disabled — NextAuth requires cookies for session management. Ensure cookies are not blocked for Voxcode’s domain in your browser settings.
  • Third-party cookie restrictions — Some browsers (Safari, Firefox in strict mode) block third-party cookies by default. Add Voxcode to your exceptions list or switch to Chrome.
  • Account already exists — If you previously signed in with Google and now try GitHub (or vice versa) using the same email address, you may hit a conflict. Contact support to merge accounts.
  • Corporate SSO conflict — If your Google or GitHub account is managed by an organization, that organization’s IT policy may block OAuth access from third-party apps. Try a personal account.
After completing a purchase, your credit balance should update within a few seconds. If it doesn’t:
1

Refresh the page

A hard refresh (Ctrl+Shift+R) forces the app to re-fetch your account state from the server.
2

Sign out and sign back in

This clears the local session cache and re-loads your account data, including the updated credit balance.
3

Wait a moment and check again

Payment webhooks occasionally take up to 2 minutes to process. Wait briefly, then refresh.
4

Contact support with your receipt

If your balance still hasn’t updated after 5 minutes, email support@voxcode.app with your account email and the purchase receipt. We will apply the credits manually.

​
Performance issues

Response latency depends on the model you have selected, your internet connection, and current server load. Here’s what you can do:
  • Switch to a faster model — Models like Gemini 2.5 Flash (~600ms), MiMo-V2-Flash (~500ms), and Grok 4.1 Fast (~800ms) are optimized for speed. For voice interactions especially, these models deliver a noticeably snappier experience.
  • Start a fresh conversation — Very long conversations accumulate context that the model must process on every request. Starting a new chat for a new task reduces input token counts and speeds up responses.
  • Check your connection — Run a speed test. Voxcode streams responses in real time, so a high-latency connection will delay time-to-first-token even if bandwidth is adequate.
  • Avoid peak hours — Like all cloud AI services, response times can vary with server load. If speed is critical, try off-peak times.
Voxcode uses streaming TTS: the AI’s voice response begins playing as soon as the first sentence is complete, without waiting for the full response. If audio feels delayed, this is usually a network issue rather than a processing issue.
Voxcode is built mobile-first, but demanding hardware can still struggle with certain features:
  • Disable the 3D Voice Orb — The animated orb uses WebGL canvas rendering, which is GPU-intensive. Go to Settings → Voice Display and switch to the classic waveform mode. This significantly reduces CPU and battery usage on lower-end devices.
  • Close other browser tabs — Mobile browsers share memory across tabs. Close unused tabs to free up RAM for Voxcode.
  • Use a lighter chat background — Animated cosmos backgrounds have a higher rendering cost than solid or pattern backgrounds. Switch to a solid background in Settings → Chat Background.
  • Install Voxcode as a PWA — Adding Voxcode to your home screen and running it as a standalone PWA can improve performance by removing the browser chrome overhead.
  • Clear browser cache — Over time, accumulated cache data can slow down localStorage reads and writes. Clear your site data for Voxcode (note: this will also clear your VFS, so export your files first).