Learn About

Deep workflow guides aligned to this documentation section.

Opta Accounts Masterclass

Account-control strategy, token posture, and multi-surface auth flows.

accounts

Browse all Opta Learn guides

Troubleshooting

Common failure modes for account login, callback relay, and cloud sync commands with direct remediation steps.

Supabase Not Configured

If login exits with a Supabase config error, required env vars are missing or empty.

Check effective Supabase auth environment

env | rg 'OPTA_SUPABASE|NEXT_PUBLIC_SUPABASE'

Set required vars

export OPTA_SUPABASE_URL="https://<project>.supabase.co"
export OPTA_SUPABASE_ANON_KEY="<anon-key>"

OAuth Timeout or State Mismatch

Browser auth fails if callback does not arrive before timeout or if callback state differs from the CLI-issued value.

Increase callback window for slow or interrupted sign-in

opta account login --oauth --timeout 600

Force canonical accounts portal origin

opta account login --oauth --accounts-url https://accounts.optalocal.com

Callback target restriction

The Accounts relay only redirects to 127.0.0.1:<port> and requires matching state. Invalid port/state always fail by design.

Keys Commands: Not Signed In

opta account keys ... requires a valid local account session with an access token.

Verify authenticated=true before running key sync commands

opta account status --json

Re-authenticate, then retry keys list/push/delete

opta account login --oauth

Health Endpoint Failing

Use the Supabase health gate to isolate service-level vs schema-level failures.

Accounts health check

curl -s "${OPTA_ACCOUNTS_URL:-https://accounts.optalocal.com}/api/health/supabase" | jq .

Focus fields:

services.auth.ok, services.rest.ok, services.storage.ok
schemaReady and per-table presence under tables

schemaReady=false

If services are up but schemaReady is false, required Accounts tables are missing in Supabase. Apply the current Accounts schema migration set, then re-run health.

Stale or Expired Local Session

The CLI attempts refresh when expiry is within 5 minutes. If refresh fails, session is treated as logged out.

Check whether local session is null or expired

opta account status --json | jq '.session'

Clear stale state and establish a new session

opta account logout && opta account login --oauth

OAuth Opta Browser Issues

If --oauth-opta-browser fails to open or navigate, fall back to system browser flow first, then debug cookie-jar mode.

Baseline system-browser OAuth path

opta account login --oauth

Retry Opta-managed browser session with explicit jar

opta account login --oauth-opta-browser --oauth-cookie-jar default

Clean Reset

Use this only when local account state is known-bad and normal logout/login does not recover.

Best-effort local clear + remote revoke

opta account logout

Remove persisted local session file

rm ~/.config/opta/account.json

Re-create clean account state and verify

opta account login --oauth && opta account status --json

Do not delete the entire config directory

Limit cleanup to account.json unless you intentionally want to reset all Opta CLI local state.

Sync

Overview