Troubleshooting
Large imports, error messages, and failed imports.
You’ll need: the import’s message from the Algolia card or the dialog.
How long it takes
- Captain reads products from Algolia 1,000 at a time. There’s no product limit.
- Reading stops after 10 minutes. A 500,000-product index was read in full within that limit in a test on 20 October 2026.
- After reading, Captain maps the settings, adds the products and builds the catalog. The dialog and the Algolia card show each step’s progress.
- You can close the dialog or leave the page at any time. The import keeps going on Captain’s servers.
When an import fails
When an import fails before any products were added, the console removes the empty catalog it created. It does this the next time Product Search is open in your browser. The message then says “Nothing was changed”, and you can import again with the same name.
If products were already added, the catalog is kept, and the message says it was left with part of the products. Open the catalog, select Delete catalog, then import again. Retry import asks for a new catalog name, because the old one now holds products.
The console only removes a catalog that it created for this import and that is still empty.
This API key can change your Algolia data
The key has a write right, such as addObject or editSettings. Create a key with only browse and settings. See Make a read-only key.
Algolia did not recognize this API key
The key and the Application ID don’t belong together, or it’s your Admin API Key, which Captain doesn’t accept. Check both in Algolia under Settings, API Keys, and use a key you created with only browse and settings.
This API key cannot read products
The key has no browse right. Add it in Algolia and import again.
That Algolia application ID wasn't found
The Application ID is mistyped. Copy it from Algolia’s API Keys page.
Algolia has no index with that name
Check the spelling. Index names are case sensitive.
Reading from Algolia took longer than 10 minutes
The import stopped before it changed anything. Contact Captain support, and we’ll import it for you from an export.
That catalog name is taken
Imports always create a new catalog. Pick a name no catalog uses.
An import into this catalog is already running
Only one import per catalog runs at a time. Wait for it to finish.
The import was interrupted on our side
A Captain server restarted during the import, and the key isn’t kept, so it can’t resume. Start it again.
Captain could not reach Algolia
A network problem between Captain and Algolia. Try again in a minute.
The products were imported, but the catalog could not be made searchable yet
The products came over, but building the catalog didn’t finish. Open the catalog to run the update again. If the import summary says another update is running, the catalog becomes searchable when that update finishes.
Search settings, synonyms and rules were not read
The products came over, but the key has no settings right. Add it and import again into a new catalog.
Good to know
- An import always creates a new catalog. To refresh one, import again under a new name and switch your site to it when it’s ready.
- An import doesn’t keep the catalog in sync with Algolia. It copies the index once.
- Coming soon: an interrupted import resumes where it stopped, and a failed import removes everything it added.