Troubleshooting

Search returns no results

The most common cause is a vector-dimension mismatch after switching providers. Different embedding models produce vectors of different sizes (OpenAI text-embedding-3-small is 1536, Voyage is 1024, etc.), and Spectacles deliberately only compares vectors of matching shape.

Fix: open Settings → Plugins → Spectacles and click Re-index all images.

The vision API call is failing

Check the Craft logs (storage/logs/web.log or your queue runner’s log) for the actual error message from the provider. Common culprits:

• Missing API key. The setting must reference an env var that exists at runtime — e.g. $OPENAI_API_KEY with OPENAI_API_KEY=sk-... in .env.
• Image too large. Most vision APIs cap upload size. Resize before saving, or transform in Craft.
• Rate limit hit. Spread out the re-index by working through the queue more slowly.

Visitor upload returns 403

Allow public visitor uploads is off in settings. Toggle it on, or update the public endpoint to require authentication.

pgvector backend isn’t being used

Check, in order:

1. Are you actually on Postgres? php craft env will show your driver.
2. Is the extension installed? SELECT * FROM pg_extension WHERE extname = 'vector';
3. Was the migration run? spectacles_imagevectors should exist.
4. What does the CP sidebar show under “Backend”? If it says scan, one of the above failed silently.

Sidebar panel doesn’t appear

The sidebar uses the Element::EVENT_DEFINE_SIDEBAR_HTML event for assets. If your install overrides asset templates heavily, the event may not fire on the page you’re viewing. The cp.assets.edit.details legacy hook is a fallback — open an issue and we’ll wire it for you.

Queue jobs are stuck

If you’re running the queue via a web request rather than a worker, large libraries will time out mid-re-index. The fix is to run a queue worker:

php craft queue/listen

Or schedule queue/run to fire every minute via cron.

Embeddings for visitor uploads look wrong

Make sure the same embedding provider produced both the visitor query embedding and your stored embeddings. If you switched providers without re-indexing, queries will return nothing (see “Search returns no results” above).

Still stuck?

Open an issue at github.com/justinholtweb/craft-spectacles/issues with the relevant log excerpt and your Spectacles settings (with API keys redacted).