Troubleshooting¶
Checks for the Chroma failures the published getting-started page names.
chroma does not become active¶
Cause: first boot has not finished, or the listener configuration was changed. The launcher rejects a changed listener so it does not open an unexpected address.
Fix: read the unit status and the recent log. Put the listen address
back if you edited it. Do not delete /var/lib/chroma.
sudo systemctl status chroma sushi-chroma-firstboot sushi-chroma-ready
sudo journalctl -u chroma --since '10 minutes ago'
If startup still fails, keep the data and the error text, and email info@softwaresushi.com.
A client on another machine is refused¶
Cause: the API is on 127.0.0.1:8000 only. An inbound security group
rule does not publish it.
Fix: forward port 8000 with Session Manager, or open an SSH tunnel to that port. See Reach the API.
The query result is not alpha¶
Cause: the check query is [0.95, 0.05] against the demo collection.
The published guide expects nearest ID alpha at squared L2 distance
0.005. A different query, a different collection, or vectors you added
later will change the neighbor.
Fix: rerun the read-only command on the demo manifest:
Use your own embeddings in application requests. Leave the default embedding function off.
Authentication headers are ignored¶
Cause: this build does not implement application authentication. Legacy
CHROMA_SERVER_AUTHN variables do not protect the port.
Fix: restrict who can log in to the instance, and keep the forwarded port on a machine you trust. Local users can call the API.
Restored data does not query¶
Cause: the restore omitted /etc/chroma or /var/lib/chroma, changed
numeric ownership, or moved the files onto a different application version.
Fix: stop the service, restore both directories from the same archive,
preserve numeric ownership and modes, start the service, and run
sushi-chroma read before writes.
Last updated October 27, 2026 · Suggest an improvement