Skip to content
Strata
Strata is pre-1.0. APIs, protocol, and storage format may change.

Troubleshooting

just: command not found or wrong Gleam/Erlang version

Section titled “just: command not found or wrong Gleam/Erlang version”

Tool versions are pinned in .tool-versions and installed by mise:

Terminal window
mise install

Then re-open your shell so just, gleam, and erl resolve to the pinned versions.

Dependencies are missing or out of date

Section titled “Dependencies are missing or out of date”
Terminal window
just deps

If a build or test fails after changing dependencies:

Terminal window
just clean
just deps
just build-all
just test-all

Port 8000 is already in use

Section titled “Port 8000 is already in use”

Another Strata server or another process is listening. Stop the other process. You cannot change the port with an environment variable. If you embed the server, set port in StrataConfig.

WebSocket connection is rejected with 403

Section titled “WebSocket connection is rejected with 403”

The token in the URL does not match STRATA_TOKEN on the server, or is missing. Check:

  • the URL includes ?token=…;
  • the value matches exactly what the server was started with (the development default is dev-strata-token);
  • you set STRATA_TOKEN in the same shell that ran just server or just example.

http://localhost:8000 returns 404

Section titled “http://localhost:8000 returns 404”

The server is running but STRATA_STATIC_DIR is not set, so there is nothing to serve at /. Use just example <name>, which sets it for you, or set it yourself. The WebSocket endpoint and /admin still work.

Admin page is blank or says "Token required"

Section titled “Admin page is blank or says "Token required"”

Open it with the token in the URL: http://localhost:8000/admin?token=<STRATA_TOKEN>. If the page is 404, the SPA has not been built: run just admin-build.

Two tabs do not sync

Section titled “Two tabs do not sync”

Both tabs must join the same document id with the same token. Check the server log for rate-limit errors if one tab sends many messages at once. The default limit is 20 messages per second for each connection.

A frame returns a protocol error

Section titled “A frame returns a protocol error”

Check that the frame has "v": 0 and a supported kind. Then check the required fields on the Protocol page. Handle strata_client.ProtocolError as invalid server data. Handle strata_client.ServerError as a valid error response from the server.

The server cannot open its data directory

Section titled “The server cannot open its data directory”

Confirm that the process can create and write files in STRATA_DATA_DIR. Only one server process can own a given DETS data directory. Stop any other process that uses the same directory.