Skip to content

Troubleshooting

If you are having trouble running Marqo then see below for potential solutions. If these do not work then you can get help by raising an issue or by joining our Slack community. See Community and Support for further details.

RAM and VRAM

Depending on the settings used, Marqo can consume more memory (RAM or VRAM) than is available. Symptoms of exceeding system memory can include abrupt termination of Marqo with the message Killed. To reduce memory consumption, the following actions can be performed:

  • Do not load any models at startup. This will avoid pre-loading models and will reduce the memory footprint of Marqo. This can be achieved by adding the environment variable - -e MARQO_MODELS_TO_PRELOAD='[]' - to the Marqo docker run command. See Configuring preloaded models

Batch or request sizes are too large

Large batches of documents when indexing can degrade performance or reduce throughput, including when using Marqo Cloud. It is recommended to send documents for indexing in batches. The python client makes this easy to do by setting a client_batch_size parameter when indexing. Having a larger batch size reduces the communication overhead from sending more requests.

Marqo Cloud

It is recommended to not send very large batch sizes as timeout limits (for Marqo Cloud) can occur. The exact batch size will vary greatly on the document structure and models used. For typical scenarios client_batch_size=64 is a good starting point. Alternatively, choose batch sizes that keep indexing requests to < 10 seconds. The times can be observed in the log outputs of the python client.

response = mq.index("my-index").add_documents(
    documents, client_batch_size=64, tensor_fields=["myField"]
)

Documents are too large

Very large documents may cause issues during indexing due to request limit sizes. There are several options to remediate this:

  • Break large documents into multiple smaller documents.
  • Modify the MARQO_MAX_DOC_BYTES environment variable described in the section Configuring usage limits.

Running Marqo on older AMD64 processors

Marqo's built-in vector store is compiled to exploit advanced CPU instructions that may not be available on older AMD64 processors. If your processor does not support the required instructions, you may observe the following warning when starting Marqo: 

Warning: Failed to configure local vector store. Marqo may not function correctly
followed by other errors due to the vector store not being available. To get around this, you can run the vector store externally using a Docker image built for older processors: 
docker run --detach --name vespa -p 8080:8080 -p 19071:19071 -p 2181:2181 vespaengine/vespa-generic-intel-x86_64
Now deploy an initial application package to configure the vector store. An application package suitable for local runs is provided in the Marqo repository: 
git clone https://github.com/marqo-ai/marqo.git
cd marqo
(cd scripts/vespa_local && zip -r - * | cURL --header "Content-Type:application/zip" --data-binary @- http://localhost:19071/application/v2/tenant/default/prepareandactivate)
You can verify that the vector store has been set up correctly by visiting http://localhost:8080 in your browser. The vector store can take a few minutes to start responding after the initial configuration.

With your external vector store ready, you can now run Marqo configured to use it: 

docker run --name marqo -p 8882:8882 --add-host host.docker.internal:host-gateway \
    -e "VESPA_CONFIG_URL=http://host.docker.internal:19071" \
    -e "VESPA_QUERY_URL=http://host.docker.internal:8080" \
    -e "VESPA_DOCUMENT_URL=http://host.docker.internal:8080" \
    marqoai/marqo

Image search results are poor

If results obtained when searching across an index of images are poor, it could be due to misconfigured index settings. You must make sure that URLS and pointers are being properly downloaded. Specifically, the following setting needs to be enabled on index creation:

treat_urls_and_pointers_as_images=True (if using Python client create_index parameter).

treatUrlsAndPointersAsImages: True (if using the REST API or settings_dict).

To check the settings of the index, see here. To see the available image models, refer to the "Image" section of the models reference in the documentation.

Other Issues

If your problem cannot be solved by these suggestions then you can get additional support from Slack or Github. See Community and Support for details.