Troubleshooting

Every entry here is a real symptom with a real cause. Start with the four at the top: between them they account for most of the time anyone loses with Baselyra.

My query returns no rows

You call a table you can see in the Studio, and get this:

curl -s "$URL/rest/v1/notes?select=id,title" -H "apikey: $ANON_KEY"

[]

Almost always row level security, and it is working correctly. A policy denial is not an error — it is an empty array with a 200, because whether a row exists is itself information a policy can withhold.

1. Check whether the table has policies at all

   select c.relname as table,
          c.relrowsecurity as rls_enabled,
          count(p.polname) as policies
     from pg_catalog.pg_class c
     join pg_catalog.pg_namespace n on n.oid = c.relnamespace
     left join pg_catalog.pg_policy p on p.polrelid = c.oid
    where n.nspname = 'public' and c.relkind in ('r','p')
    group by 1, 2
    order by rls_enabled, 1;

   RLS on and zero policies means the table denies everything to anon and authenticated. That is the safe default, not a bug — write a policy.

2. Check which role you were

   An apikey alone is anon. A policy written for select to authenticated admits nothing to an anonymous caller. Send the user's access token as authorization: Bearer … as well.

3. Reproduce it as that user, in SQL

   begin;
     select set_config('role', 'authenticated', true);
     select set_config('request.jwt.claims',
       '{"sub":"6c1f5c62-8e4c-4a6b-9a54-1c9d0a0d1a11","role":"authenticated"}', true);
     select * from public.notes;      -- exactly what that user sees over REST
   rollback;

   The Studio's grid runs with BYPASSRLS, so it shows the whole table whatever your policies say. This block is the only honest test.

Realtime connects but nothing ever arrives

The socket opens, subscribe() resolves SUBSCRIBED, and no event ever comes. There are exactly two causes.

1. The table has no trigger

Change feeds are opt-in per table.

select * from baselyra.realtime_tables;
select baselyra.enable_realtime('public.messages');

2. The proxy is eating the Upgrade header

One command settles it. A 101 is the whole test:

curl -i -N \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  "https://api.example.com/realtime/v1?apikey=$ANON_KEY"

The working configurations are in deploy/. On Apache the rewrite must come before the catch-all ProxyPass, or the WebSocket is proxied as plain HTTP:

RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule ^/?(.*) ws://127.0.0.1:3130/$1 [P,L]

ProxyPass        / http://127.0.0.1:3130/
ProxyPassReverse / http://127.0.0.1:3130/
ProxyTimeout 300

sudo a2enmod proxy proxy_http proxy_wstunnel rewrite headers ssl

On nginx, proxy_http_version 1.1 and both Upgrade headers, on every location:

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

location / {
    proxy_pass http://127.0.0.1:3130;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 300s;
    proxy_buffering off;
}

No email ever arrives

Sign-up succeeds, the confirmation never comes, and nothing looks broken.

docker compose logs app | grep '\[mail\]'

[mail] SMTP not configured, would have sent to <ada@example.com>
[mail]   subject: Confirm your email address
[mail]   link:    http://127.0.0.1:3130/auth/v1/verify?token=8Yb…&type=confirmation

Open that link in development. For production, configure a relay and restart:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false          # true only for implicit TLS on 465
SMTP_USER=…
SMTP_PASS=…
SMTP_FROM="Acme <no-reply@acme.com>"

docker compose up -d

Then Studio → Email → Send test, which uses your real templates and reports the SMTP error verbatim.

The Studio will not let me in

You created a user, the sign-up worked, and /login refuses those credentials.

Use the credentials ./scripts/setup.sh printed on the first boot. If they are lost:

# put a new bootstrap password in .env and restart — migrate.js only sets the
# password when it CREATES the account, so first remove or rename the old row.
docker compose exec db psql -U baselyra -d baselyra_control \
  -c "select id, email, role_slug from control.platform_users;"

Then either delete that row and restart with BASELYRA_ADMIN_EMAIL and BASELYRA_ADMIN_PASSWORD set, or ask another owner to reset it from Studio → Settings → Team.

An import says a table already exists

{"error":{"code":"import_rejected",
  "message":"public.posts already holds 4812 rows — deselect it, or choose replace mode",
  "details":null}}

This is the guard, not a fault. mode: "create" — the default — refuses to write into a target table that already holds rows, and names the table.

The instance will not start

HTTP status quick reference

Things that look broken and are not

Collecting evidence

curl -s https://api.example.com/health                  # is it up, are both databases up
docker compose ps                                       # healthy?
docker compose logs --tail=200 app
docker compose logs --tail=200 db
docker compose exec db psql -U baselyra -d baselyra -c '\dt public.*'
docker compose exec db psql -U baselyra -d baselyra_control -c 'select count(*) from control.platform_users;'

Then the end-to-end check, which drives auth, REST, storage, realtime, the admin API and the Studio the way a real client would:

./scripts/smoke.sh http://127.0.0.1:3130 admin@example.com 'password'

Edit this page Report a problem