Symptom → cause → fix, across install, dashboard, S3, and storage. For defects open
in the current beta specifically, see Known issues.
Install & startup
“port is already allocated” / “address already in use”
Something else is using 8888, 9000, or 9443. Set UI_PORT / S3_PORT /
S3_TLS_PORT in the .env next to your compose file and docker compose up -d
again. Portainer commonly holds 9443 — move S3_TLS_PORT to 9444.
“unauthorized” / “denied” when pulling the image
The builds are public; a pull never needs credentials. A stale login from an
earlier private build causes this — docker logout releases.scpri.me and pull again.
“permission denied” / “cannot connect to the Docker daemon”
Docker isn’t running (open Docker Desktop and wait for “running”), or on Linux your
user isn’t in the docker group.
Container won’t start or restart-loops
docker compose logs --tail=100 and read the last error. If you’re an invited
tester, paste it in the Discord channel — the automatic crash reporting already
sent us the stack trace, but not what you were doing.
Upgrading from an earlier beta: GATEWAY/HOSTIO ports changed
Internal defaults moved (GATEWAY 34554 → 5500, HOSTIO 37809 → 3480) to dodge a
boot-ordering race. Fresh installs: nothing to do. Old installs that persisted the
old ports and crash-loop with bind: address already in use: set GATEWAY_PORT
to 5500 and HOSTIO_PORT to 3480 in device config and restart.
Dashboard
Can’t reach the dashboard
Use http://localhost:8888 (http, not https) and confirm
docker compose ps shows the relayer container running.
Buckets look empty after an upgrade
You previously ran a bind-mount (./data:/relayer or similar) and the new compose
uses the relayer_data named volume — the Relayer now refuses to start over a
stranded database instead of showing an empty box. Either point the volume line
back at your folder (/your/path:/relayer), or copy the old data into the named
volume with the stack stopped. Custom old path? Set LEGACY_DATA_PATH=/your/old/path
in .env so the safety check watches the right folder.
Monitoring charts are empty
The Grafana/Prometheus sidecars aren’t up, or a scrape target is down. Check
Monitoring → Node Health → Prometheus Targets Up, then
docker compose ps — you should see prometheus, grafana, and node-exporter
containers next to the relayer.
Figures look frozen
Node Health → Bridge Collector Freshness climbing without reset means the
internal metrics bridge is stale — reload first, then restart the container if it
persists.
S3 clients
Access Denied on every request from an IAM user
Three ladders, in order:
- The credential has no policy attached — attach ReadWrite/ReadOnly in IAM.
- The Denied tab reads 0 but All Events shows AUTH_FAILED — the signature or
key is wrong (typo’d secret, clock skew). - Everything is attached and correct but every request still fails with the
gateway log linein-account principal with unresolved owner — failing closed
— a known beta issue; see Known issues. The install root
credential (Configure → Credentials) still works.
Client works over HTTP but not HTTPS
TLS lives on 9443, and http://<host>:9000 keeps working after you install a
certificate — the encrypted endpoint is additional. Self-signed cert? Tell the
client to skip verification (rclone no_check_certificate = true; AWS CLI
--no-verify-ssl).
rclone / GUI client fails with a WriteOnly credential
By design: WriteOnly allows PUT/DELETE but not the stat/list most tools do before
writing. Use ReadWrite for those tools; WriteOnly is for direct-PUT pipelines.
SSE-C or aws:kms encryption rejected
Not implemented — intentionally. All data is already encrypted at the gateway
(XChaCha20) before sharding; plain uploads are protected. --sse AES256 is
honored if a workflow demands the S3 contract.
Storage & durability
Storage services stay down after a fresh install
A brand-new (or wiped) box hasn’t completed its claim/onboarding, so HostIO,
Gateway, and S3 Gateway wait for an identity. Finish the claim flow; watch
Configure → Services go RUNNING.
Uploads slow
Expected order of magnitude on small hardware is ~5–7 MiB/s per PUT stream —
CPU-bound, so more cores = more throughput. Check Network Overview: if host CPU
is pinned but container CPU is low, another process is stealing the machine. Cap
the Relayer with a cpus: limit in compose only if you want it throttled.
Machine running hot
Add cpus: 1.0 (or a fraction) to the relayer service only in
docker-compose.yml, then docker compose up -d. Don’t throttle the monitoring
containers.
Repair keeps running
Normal — providers churn and repair re-shards affected rows in the background.
Worry only when Rows Failed climbs across passes or Confirmed Lost is
non-zero: capture the Repair & Durability screen and report it.
Getting help
Every bug report should carry: the build stamp (sidebar bottom, e.g.
beta-a4b855e), dashboard version (footer), what you were doing, and
docker compose logs --tail=100 when the container is involved. Crashes and 5xx
errors are auto-reported with your build tag — your description of the context is
the half we can’t collect.
