Something's wrong? · Teserra Docs

The browser extension can’t reach Teserra

Is Teserra open on this Mac?

If not: Open it. The extension only talks to the app running on this Mac, at 127.0.0.1:8788, never to a server.
Does 127.0.0.1:8788/health show ok in your browser?

If not: Teserra is not answering on its port. Quit and reopen it. If that changes nothing, another app may hold port 8788: quit apps that run a local server, then reopen Teserra. Agent access uses the same port, so it stops too.
Did you paste the token from Settings›Browser?

If not: In Teserra, Settings›Browser, click Copy pairing token, paste it in the extension's popup and click Connect. The popup itself still says “Settings → General → Browser clipper”: the button has moved to the Browser tab. If the button is missing, turn on Links or Articles in Settings›Add-ons; the extension needs one of them.
Is the port in the extension set to 8788?

If not: Set it back to 8788 in the popup or in the extension's Options. Teserra always listens there.
Does the Option-click (Quick save) work?

If not: Open the extension's Options, Turn on Quick save and accept the browser's request for site access, then reload the tabs that were already open. In Safari, allow the extension on every website in Safari → Settings → Extensions.

If you see	What it means
Teserra is not running. Open the app, then connect again.	Teserra is closed, or another app holds port 8788.
That token was refused. Copy it again from Teserra.	Copy pairing token in Settings → Browser, paste it again.
Teserra is not running, or the clipper port is different.	Open Teserra; the port must be 8788.
Wrong clipper token. Copy it again from Teserra settings.	Copy pairing token in Settings → Browser, paste it in the Options.
Paste your clipper token in the extension options, then try again.	The extension has no token yet. Its Options open by themselves.
Links is turned off in Teserra. Turn it on in Settings, Add-ons.	Same for Articles. Turn the add-on on, or save the page another way.
This site refused the download. Try opening the image in its own tab, then send it from there.	The site blocks reading the image from its page.
This image only exists inside the page and could not be read.	The page draws it itself; take a capture with ⌘⇧M instead.
This video is streamed and cannot be saved.	YouTube, Vimeo or Instagram stream video. On X, open the post itself, then Option-click its video.
This video is over 100 MB	Larger videos are refused from the browser; download the file and drop it in Teserra.

⌘⇧M does nothing

Does Settings›Capture say the Screen Recording permission is Allowed?

If not: Click Open System Settings on that row, turn on Teserra under “Screen & System Audio Recording”, then quit and reopen Teserra if captures still fail. Without it, a ⌘⇧M pressed in another app shows nothing until you switch to Teserra, which asks for it there.
Was it ⌘⇧M, the area capture?

If not: Only the area capture works from any app. ⌘⇧W, ⌘⇧S and ⌘⇧F work while Teserra is in front. From anywhere, the menu bar icon offers all four.
Is ⌘⇧M free of other apps?

If not: Another app may take the shortcut first. In Settings›Capture, click the Capture area shortcut and press a new one; it needs ⌘, ⌃ or ⌥. If you see “Could not register this shortcut”, pick another.

If you see	What it means
Capture failed: … If this mentions permissions, check Screen Recording for Teserra in System Settings → Privacy & Security.	The permission is missing or macOS wants Teserra reopened.
Could not register this shortcut: …	macOS refused that combination. Try another one.
Bypassing the system private window picker	A macOS dialog every screenshot app gets on macOS 15 and later. Allow keeps things as they are.

Search by meaning finds nothing

Does Settings›Add-ons›Visual search say Installed?

If not: Click Install: about 300 MB, once, and it runs on your Mac. Search by meaning runs on it. The search field does not tell you when it is missing.
Is the index finished?

If not: While it builds, the grid says “Still indexing your images, results by meaning will improve in a moment.” Wait, or open the Visual search options and click Index the rest.
Are you looking for images or videos?

If not: Only images and videos are searched by meaning. Links, articles and fonts are found by their words: title, text, site.
Are you in All, with no filter on?

If not: Search and Find Similar stay inside the collection and the filters you are in. Open All and clear the filters.

If you see	What it means
Still indexing your images, results by meaning will improve in a moment.	The visual index is still being built.
Nothing matches. Try clearing search or filters.	Nothing came close enough, in the scope you are in.
This item is not in the semantic index.	Find Similar on an item that is not indexed yet: with Visual search installed, wait for the index to finish.

My AI client doesn’t see Teserra

Is Teserra open?

If not: Agent access is served by the app itself. Open Teserra, then reconnect your client (in Claude Code, /mcp).
Is Agent access on in Settings›Add-ons›Agent access?

If not: Switch it on. Off, the server answers “Agent access is turned off in Teserra”.
Was the line copied from Teserra, with its token?

If not: Copy it again from the same page, Copy, and add the server again. In Claude Code: claude mcp remove teserra, then the line you copied. A wrong token gets “unauthorized”.
If it needs to change something, is Allow changes on?

If not: Turn on Allow changes on the same page, then reconnect your client so it sees the tools that write.

If you see	What it means
Agent access is turned off in Teserra. Turn it on in Settings, Add-ons.	The switch is off.
unauthorized	The token in your client is not Teserra's. Copy the line again.
Changes are not allowed. The user can turn on 'Allow changes' in Teserra, Settings, Add-ons, Agent access.	Turn on Allow changes, then reconnect the client.
Constellation needs visual search: install the local model in Settings → Add-ons → Visual search.	Install Visual search.
The library is not indexed for visual search yet.	Wait for the visual index to finish.

The Curator writes nothing

Does Test connection say Connected, in Settings›Add-ons›Curator?

If not: Read what it says instead: the messages are below. Fix the key, the model or the credit, then test again.
Does your model read images?

If not: Test connection only checks that the model answers. A model without vision catalogs nothing. With OpenAI, the mini models read images.
Did the last run give your items a title?

If not: A run that failed on the provider's side still ends as done. Once the test says Connected, open File → Curator… and click Fix next to the items without a title or tags.
Is Curate automatically on?

If not: New imports are only cataloged on their own with Curate automatically on, in the same options. It is off by default.

If you see	What it means
Connected. gpt-4o-mini answered in 0.8 s.	All good.
Paste your API key first.	The key field is empty.
The key was refused. HTTP 401: …	Wrong or revoked key.
The model or the endpoint was not found. HTTP 404: …	Check the model name and the endpoint.
Rate limit or no credit on this key. HTTP 429: …	Add credit with your provider, or wait.
Could not reach http://localhost:11434/v1. Check the endpoint, or that your local server is running.	A local endpoint that is not running, or a typo.
AI key not configured (see Settings).	No key saved.

A file won’t come in

Did you use File → Import Folder… for a folder?

If not: Dropping a folder on the grid does not import it. Use File → Import Folder…; it reads the subfolders too.
Is it a WebM, MKV or AVI video?

If not: Install ffmpeg (brew install ffmpeg), then import it again. MP4 and MOV need nothing.
Is the file on this Mac, not only in the cloud?

If not: Files that iCloud Drive or another cloud keeps online only are skipped. Download them, then import again.
Is your trial still running?

If not: After the trial, the library stays readable but nothing new comes in. License and Macs

If you see	What it means
WEBM files are not supported	Shown with the extension of the file. See the formats in Adding things.
Teserra cannot decode this WEBM video. MP4 and MOV work out of the box; for WebM, MKV or AVI install ffmpeg (brew install ffmpeg).	Install ffmpeg.
RAW file(s) skipped: macOS cannot decode this camera's format yet.	macOS does not read that camera yet. The files stay where they are.
image(s) skipped: not downloaded (online-only).	Make the folder available offline, then import again.
Your free trial has ended. Activate a license to keep using Teserra.	Buy or enter a license.
This item is already in your library.	Same content, already there: nothing is added twice.

My license won’t activate

Did you paste the whole key?

If not: Copy it again from the email, all of it, and paste it in Settings → License.
Is it on fewer than three Macs?

If not: Activate from Settings → License: it lists the three Macs with their last activity, and Sign out frees one on the spot.
Do you have the key at hand?

If not: In the app, Lost your key?, then Send my key with the email you bought with.

If you see	What it means
This license key is invalid. Check that you pasted it entirely.	Part of the key is missing.
This license is already on 3 Macs. Open Settings → License to sign one out, then activate.	Activate from Settings → License to choose which Mac to sign out.
This license has been revoked.	Write to [email protected].
If a license exists for this address, the key is on its way.	Check your inbox and spam for the address you bought with.

Updates fail

Is this Mac online?

If not: Connect, then Teserra → Check for Updates…
Did it fail again a few minutes later?

If not: Download Teserra from teserra.app and replace the app in Applications. Your library is a folder of its own: nothing in it changes.

If you see	What it means
Couldn't reach the update server. Check your internet connection and try again.	No connection, or the server could not be reached.
Couldn't check for updates right now. Please try again in a few minutes.	Try again later.
Couldn't download the update. Check your internet connection and click Install again.	The button reads Install and restart.

Not here? Press ⌘K and paste the message Teserra shows, or ask on Support.

PreviousKeyboard shortcuts Getting started