Troubleshooting

SDK import fails

Import opencloud from /_opencloud/sdk.js. Confirm that stable path returns JavaScript and /_opencloud/sdk.d.ts returns declarations for the active release. Do not fetch runtime config, construct a client, or import a guessed versioned artifact.

AUTH_REQUIRED

An OpenCloudError with code AUTH_REQUIRED means the operation needs a signed-in user. In a public app, render sign-in UI or choose a deliberately public read/Function. In a private app, retry the brokered session and inspect the central Auth redirect.

A data query 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.

File upload fails

Check that the schema 2 or 3 manifest declares files, that the user is signed in, and that the Blob fits files.maxUploadBytes. Pass the Blob directly to opencloud.files.upload; do not construct a Storage path or auth headers. For a database-backed attachment, use files.attach and handle FILE_ATTACHMENT_INCOMPLETE by retaining details.file.id for cleanup.

Function returns 401

Declare a browser Function with access: user or public, then call opencloud.functions.call or stream. Declare cron targets, queue consumers, and inbound-email handlers system; a browser attempt receives FUNCTION_SYSTEM_ONLY. Do not call Function URLs manually.

A background job does not enqueue

Check the bounded error code before retrying:

Code	Meaning and recovery
QUEUE_NOT_DECLARED	The active manifest does not contain that exact queue name. Add or correct the declaration and deploy or sync it.
INVALID_IDEMPOTENCY_KEY	Supply a stable key between 1 and 128 characters using letters, numbers, ., _, :, or -.
IDEMPOTENCY_KEY_REUSED	The same key was already used with a different input in this app, environment, development namespace, and queue. Use the original input or a new semantic key.
JOB_PAYLOAD_TOO_LARGE	Reduce the JSON object below 64 KiB. Store larger content in data or managed Files and enqueue its opaque identifier.
JOB_QUEUE_LIMIT_EXCEEDED	The namespace already has 10,000 active jobs. Let work drain or repair the failing consumer before enqueueing more.
JOB_DISPATCH_FAILED	The broker could not accept the job. Treat this as a transient platform failure and retry with the same idempotency key.

jobs.enqueue(..., { timeoutMs }) controls only how long the producer waits for the broker request. Manifest queues[].timeoutSeconds controls how long each consumer attempt may run. Increasing one does not change the other.

A background job failed or stopped moving

Open the app's Background jobs section or use the owner job API/full MCP tools to inspect queue depth, retry count, safe error metadata, and the Agent Feed failure event. Payloads and idempotency keys are intentionally not exposed on those diagnostic surfaces.

• JOB_FUNCTION_FAILED records a consumer failure. Throw errors.unavailable(...) only when retrying is safe; other expected errors are terminal.
• QUEUE_NOT_ACTIVE means the queue was removed from the active manifest before dispatch. The job is dead-lettered and must be replaced by a new enqueue after the queue is restored.
• A suspended, archived, or transiently non-active production app pauses pending work by rescheduling it without consuming a logical attempt. Delivery resumes after the app becomes active.

Delivery is at-least-once, so consumers must make database and external side effects idempotent. There is no manual acknowledgement, cancellation, or dead-letter redrive API. After repairing a terminal failure, enqueue new work with an appropriate idempotency key.

Realtime does not connect

Ensure the visitor has a brokered session and call opencloud.realtime.subscribe(topic, handler). The promise resolves after the private topic joins. Do not construct app topics, open a WebSocket, or implement heartbeat and reconnect logic.

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.