Troubleshooting

For problems with the self-hosted stack's network, see Tailscale troubleshooting.

Building and startingCopy Anchor Link

The first build runs out of memory or freezes the machine. The first build compiles DataFusion, Lance and Tantivy. With less than 32 GB of RAM, limit parallel jobs: cargo build --release -p loams -j 4.

The build fails looking for protoc. Install the Protocol Buffers compiler: apt install protobuf-compiler, brew install protobuf or pacman -S protobuf. The Rust SDK needs it too, because loams-proto generates code at build time.

The engine refuses to start on a non-loopback address. With authentication off (LOAMS_AUTH_MODE unset or off), the engine binds only to loopback. Set an auth mode before you bind --listen elsewhere, and give the listener TLS (LOAMS_TLS_CERT_FILE and LOAMS_TLS_KEY_FILE). Loams Live refuses a non-loopback --listen without TLS; pass --no-live to run the rest of the engine there.

oidc mode refuses to start. It needs one of LOAMS_OIDC_ALLOWED_EMAILS, LOAMS_OIDC_ALLOWED_SUBJECTS or LOAMS_OIDC_ALLOWED_GROUPS.

/ready does not return 200. Readiness waits for the metastore to have a leader. Check the engine's log; with --meta tikv://… or in the compose stack, check that TiKV and PD are healthy (docker compose ps).

Calling the APICopy Anchor Link

401 from the engine. The request carried no credential the current mode accepts. With apikey, send Authorization: Bearer lk_…, and check that the key's hash is in LOAMS_API_KEYS_FILE and the engine was restarted after you appended it. Over a tailnet from a tagged device, Tailscale identity headers are empty, so tailscale mode cannot admit it: use an API key.

feature_not_in_variant. This build does not serve the package you called (for example loams.graph.v1 without the graph feature, or RepoService in the release images). Check with the SDK's system.guard(...) or GetInstance's served services, or rebuild with the feature.

house_not_configured. The engine is not wired to Loams House. Set LOAMS_HOUSE_ENDPOINT (see the deploy README), or use the House's own tailnet URL.

A read misses a write made by another process. Pass the write's Loams-Consistency-Token on the read. See Consistency tokens.

ORDER BY _id sorts 1, 10, 100. Over SQL a collection's _id is text whatever its keys are. Use ORDER BY CAST(_id AS BIGINT) for integer keys.

A write over the Postgres wire fails with SQLSTATE 25006. The Postgres and MySQL wire listeners are read-only. Write through the REST API, an SDK, or a Qdrant or Elasticsearch client.

A Qdrant or Elasticsearch collection is not where you expected. Requests without a Loams-Namespace header go to the default namespace.

The bucketCopy Anchor Link

Writes fail with Error performing PUT http://169.254.169.254. The engine found no object-store credentials and asked the cloud metadata service, which answers only on a cloud VM. In the compose stack, check that secrets/engine.env exists and sets AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

The object store rejects writes. The store needs conditional writes (If-None-Match and If-Match on PUT). AWS S3, Cloudflare R2, GCS, Azure, MinIO and RustFS support them. The bucket must already exist.

InstallingCopy Anchor Link

macOS says the app or binary is damaged or cannot be opened. The builds are ad-hoc signed and not notarized. Run xattr -dr com.apple.quarantine /Applications/Loams.app (or the path to the loams binary) once.

Windows shows "Windows protected your PC". The builds are unsigned. Choose More info → Run anyway, after you have checked the checksum.

gpg --verify reports no public key. Import the release key first: curl -fsSLO https://loams.dev/gpg.asc && gpg --import gpg.asc.

Still stuckCopy Anchor Link

Open an issue at github.com/ostrium-labs/loams/issues with the version, your LOAMS_AUTH_MODE, and the failing service's log (docker compose logs <service> in the stack). Remove tokens, API keys and TS_AUTHKEY from anything you paste. Report security issues privately, through a GitHub security advisory or to security@ostriumlabs.org, not in a public issue.