Skip to content


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.

HD space

By default, Marqo-os requires 15% of total hard drive space to be available. If this condition is not met then non-search operations will fail with an error message such as 429 Too Many Requests. To resolve this there are several things that can be done:

  • Free up disk space on the disk Marqo is running.
  • Change the default storage location so that the new storage location satisfies the free-disk space requirement. To change the default storage location, see Changing the default storage location for Docker


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 oberved in the log outputs of the python client.

response = mq.index("my-index").add_documents(documents, client_batch_size=64)

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.

Installing Docker on an M-series Mac

The steps below can be used to install Docker on an M-series Mac.

Get Docker

Try either of the following to install Docker:


  • Install with brew: $ brew install --cask docker

Install rosetta

Install Rosetta if it is not already installed using the command below:

$ softwareupdate --install-rosetta

Run it all

Run docker by double clicking it in the Applications folder.

If using zsh terminal add Docker to path:

~$ nano .zprofile

and insert:

export PATH="$PATH:/Applications/"

After these steps, continue with Marqo setup instructions as per the M-series install instructions

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. Specifically, the following setting needs to be enabled:


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.

Something else

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