#Local / self-managed troubleshooting

Operating model: Local / self-managed

Start with local state and LRS logs:

Shell

simplestlrs status
simplestlrs logs

#Docker is missing or unreachable

If the CLI reports Required tool not found: docker, install Docker. If it reports that Docker is installed but not reachable, start the Docker daemon or Docker Desktop. Confirm that docker info and docker compose version work before retrying.

#Browser authorization expires or is denied

Rerun the exact acquisition command and complete Device Authorization. If the browser cannot open, use the printed verification URL and code. No Auth0 environment configuration is required for the normal public flow.

#Acquisition is unauthorized

An authentication rejection requires signing in again. Your account is not authorized to acquire the LRS artifact means authentication succeeded but artifact authorization was denied. Do not troubleshoot AWS, Lambda, IAM, or CloudWatch; the public action is to use an approved account or contact Simplest Data through your established support channel.

#Release is unavailable

The CLI accepts exact semantic versions only. Use the current release 1.0.1. latest and unapproved versions are not available.

#Local alias conflict

The CLI refuses to overwrite simplestdata/lrs:1.0.1 if that alias points to different content. Inspect it with:

Shell

docker image inspect simplestdata/lrs:1.0.1

Preserve evidence and resolve the unexpected local image deliberately; the CLI will not replace it automatically.

#Image is missing before start

If start says the release is not available locally, run the public acquisition command again. Start never performs governed LRS acquisition itself.

#Port is already in use

Stop the conflicting process or choose another port:

Shell

simplestlrs start 1.0.1 --port 8080

#A running stack uses different settings

Only one simplestdata-lrs Compose runtime is managed at a time. If it is already configured for another release, bind, or port, stop it before starting with new settings:

Shell

simplestlrs stop
simplestlrs start 1.0.1 --port 8080

Normal stop preserves PostgreSQL data.

#Apple Silicon shows an architecture warning

Release 1.0.1 is linux/amd64. Docker may warn while running it through emulation on Apple Silicon. Native arm64 is not supported. Confirm Docker amd64 emulation is enabled; do not replace the image with an unapproved architecture build.

#Health or readiness fails

Check both endpoints and then inspect state and logs:

Shell

curl -i http://127.0.0.1:8000/healthz
curl -i http://127.0.0.1:8000/readyz
simplestlrs status
simplestlrs logs

Readiness waits on PostgreSQL, database bootstrap, migrations, and the LRS. If a custom bind or port is active, use that address. A failure message from start directs you to the same LRS logs.