Troubleshooting

When something fails, KomaLens shows a card with the problem, an explanation, a button that fixes it and a tip. If you expand Technical details, you'll see the original message from the browser or the provider: copy it if you write to us.

Here is each error, roughly in the order they tend to show up.

I can't read this tab

Code: NO_TAB_PERMISSION

What it means. The browser didn't give KomaLens permission to capture the tab.

Why it happens. For security, Chrome and Edge only let an extension capture the page right after you click its icon (the activeTab permission). If you scan from the side panel, that click doesn't count, and the extension needs a permission for that site. The technical details usually say Either the '<all_urls>' or 'activeTab' permission is required.

How to fix it.

• Click Allow on this site. The browser will ask for access to that site only (for example, example.com). Once you accept, KomaLens retries the scan, and it won't ask again on that site.
• If you'd rather not grant permissions, click the KomaLens icon in the browser toolbar and then Scan area. That click grants access to the tab for this time.

You can remove the permission anytime from the browser's extension settings. More in Extension permissions.

The language pack is missing

Code: LANGUAGE_PACK_NEEDED

What it means. In local mode, the browser doesn't have the translation pack for your pair yet (for example, Chinese → English).

Why it happens. The Translator API downloads each language pair once, the first time it's needed.

How to fix it. Click Download pack and wait: it can take a few minutes depending on your connection. After that it works offline. You can also download it from Settings → Chrome language packs, or click Use Hybrid mode to translate right away with your provider.

Your API key is missing

Code: NO_API_KEY

What it means. You chose Hybrid or Image to API, but no provider is set up.

How to fix it. Click Set up API key and fill in the base URL, key and model, as explained in Set up an AI provider. If you don't want to use a provider, click Use local mode: it needs no key.

No text found

Code: OCR_EMPTY

What it means. The OCR found no characters in the selected area, or found them with very low confidence.

Why it happens. The selection didn't include text, was too small, or the text is heavily stylized, blurry or low-contrast.

How to fix it.

• Click Scan again and select just the bubble or line of text, with a little margin.
• For hand-drawn lettering or text with effects, click Send the image to the API: a vision model usually reads it better.
• Check in Settings → Languages that Read in matches the language of the text.

Couldn't connect to your provider

What it means. In Hybrid or Image to API, the provider didn't respond or responded with an error. You can always click Try again or Use local mode while you sort it out. The technical details show the provider's code and message; these are the most common cases:

The API key is invalid

Usually shows up as a 401 error. The key was copied wrong, was deleted or belongs to another provider. Create a new one in the provider's dashboard, paste it without leading or trailing spaces, and check that the base URL belongs to that provider.

Out of credits

Usually shows up as a 402 error or an insufficient balance message. Add credits to your provider account or pick a cheaper model.

The model doesn't exist

Usually shows up as a 404 error or “model not found”. The model ID is misspelled or the provider retired it. Pick the model from the list in Settings → API provider instead of typing it.

The model doesn't accept images

Usually shows up as a 400 error that mentions images or unsupported content. In Image to API the model needs vision. Pick a model with image input (its page on the provider's site says so) or switch to Hybrid, which only sends text.

Too many requests

Usually shows up as a 429 error. You hit your plan's request limit. Wait a moment and try again, or check your account limits.

The provider isn't responding

500, 502 or 503 errors, or no response at all. It could be your connection or a provider outage. Check your internet and the provider's status page, and try again in a few minutes.

403 or CORS error with a local model

If you use Ollama, by default it doesn't accept requests from browser extensions. Add the KomaLens origin to OLLAMA_ORIGINS: the steps for Windows, macOS and Linux are in Local models with Ollama. In LM Studio, turn on Enable CORS in the server settings.

You didn't grant the provider permission

When you set up a provider, KomaLens asks for permission to connect to its domain. If you declined, save the base URL again in Settings → API provider and accept the permission.

Your browser doesn't support local mode

Code: LOCAL_UNSUPPORTED

What it means. Your browser doesn't include the Translator API that local mode uses.

How to fix it. Update Chrome or Edge to the latest stable version. If you use another Chromium-based browser, it may not have that API. Meanwhile, click Use Hybrid mode: it doesn't depend on the Translator API. The requirements are in Local mode.

This page can't be scanned

Code: NO_VALID_TAB

What it means. You're on a page no extension can read.

Why it happens. Browsers protect their internal pages (like chrome:// or edge://), the extension store and some system screens. It's a browser rule, not a KomaLens one.

How to fix it. Click Got it and scan on a regular page.

Something went wrong

What it means. An error that isn't on this list.

How to fix it. Click Try again. If it keeps happening, open Technical details, copy the message and write to us at poullorca@proton.me or to @PoulLorca on X, saying what you were scanning and in which mode.