Troubleshooting

SDK import fails

Read /_opencloud/config and import javascriptSdk.module. Do not guess a version. Confirm the exact URL returns JavaScript and javascriptSdk.types returns declarations.

OpenCloudAuthError

The operation requires a signed-in user. In a public app, render sign-in UI or choose a deliberately anonymous operation. In a private app, retry the brokered session and inspect the central Auth redirect.

REST returns no rows

Check the app’s business RLS policy. OpenCloud’s restrictive app boundary does not itself grant row access. Confirm the table policy matches auth.uid() or the intended shared-member model.

Storage returns HTTP 400 or 403

Read storage.authorization from the manifest. For owner-prefix, the first decoded object-name segment must equal session.userId. Encode segments individually rather than encoding the complete slash-separated name.

Function returns 401

Use functions.invoke for verifyJwt: true and invokePublic for verifyJwt: false. There is no functions.request.

Realtime does not connect

Use channel(...).connect(), inspect onStateChange, and ensure the visitor has a brokered session. Do not use .on(...).subscribe() or construct app topics. SDK 0.2.1 has receiver-safe heartbeat and reconnect timers. If a deliberately pinned 0.2.0 module throws TypeError: Illegal invocation, apply its compatibility shim or move back to runtime discovery.

Telemetry looks empty

Inspect activity.telemetry.status, latestIngestedAt, sampledEntries, and truncated. Empty is not synonymous with healthy.

Cron verification times out

Use the current verifier or cron invoke; both enqueue the declared active job immediately and record the normal structured invocation. The schedule cadence does not control test timing.

Migration deploy fails

Read the preflight_migrations operation step. The full migration history is executed in a disposable constrained schema before live migration. Fix the SQL, append or replace only an unapplied migration, and deploy with a new version.