tursodatabase/turso · error · Error

Unexpected status from operation.resume(): ${status}

Error message

Unexpected status from operation.resume(): ${status}

What it means

runOperation()'s resume loop accepts exactly two statuses: DONE means the operation finished and its result can be extracted, and IO means pending IO items must be processed (processIoQueue + ioStepCallbacks) before resuming. Every other status — BUSY(4), INTERRUPT(5), ERROR(127), etc. — exits through this throw with the numeric code. It is the generic failure exit for async sync-engine operations such as connect() and sync().

Source

Thrown at bindings/react-native/src/internal/asyncOperation.ts:77

        default:
          throw new Error(`Unknown result type: ${resultKind}`);
      }
    }

    // Operation needs IO
    if (status === TursoStatus.IO) {
      // Process all pending IO items
      await processIoQueue(database, context);

      // Step callbacks after IO processing
      database.ioStepCallbacks();

      // Continue resume loop
      continue;
    }

    // Any other status is an error
    throw new Error(`Unexpected status from operation.resume(): ${status}`);
  }
}

/**
 * Process all pending IO items in the queue
 *
 * @param database - The native sync database
 * @param context - IO context with auth and URL information
 */
async function processIoQueue(database: NativeSyncDatabase, context: IoContext): Promise<void> {
  const promises: Promise<void>[] = [];

  // Take all available IO items from the queue
  while (true) {
    const ioItem = database.ioTakeItem();
    if (!ioItem) {
      break; // No more items
    }

View on GitHub (pinned to bad083fafb)

Solutions

1. Decode the numeric status against the TursoStatus enum (types.ts) to classify the failure
2. Verify connect() options: url is a valid reachable endpoint and authToken is set when required
3. Status 4 (BUSY): serialize sync operations / retry after a short backoff
4. Status 127 with valid config: inspect the ioProcessor logs for the failing HTTP exchange and report if the server response looks valid

Example fix

// before
const db = await connect({ path }); // throws: Unexpected status from operation.resume(): 127

// after
const db = await connect({
  path,
  url: process.env.TURSO_SYNC_URL,   // required sync endpoint
  authToken: process.env.TURSO_AUTH_TOKEN,
});

// Validate connect() inputs before starting any sync operation
function assertSyncConfig(opts: { url?: string; authToken?: string }): void {
  if (!opts.url || !/^https?:\/\//.test(normalizeUrl(opts.url))) {
    throw new Error('connect() requires a valid http(s) sync url');
  }
}

function isResumeStatusError(e: unknown): { code: number } | null {
  const m = /operation\.resume\(\): (\d+)$/.exec(e instanceof Error ? e.message : '');
  return m ? { code: Number(m[1]) } : null;
}

try {
  await db.sync();
} catch (e) {
  const s = isResumeStatusError(e);
  if (s && s.code === TursoStatus.BUSY) {
    await new Promise(r => setTimeout(r, 100));
    return db.sync(); // bounded retry
  }
  throw e; // 127 etc. → inspect config/logs before retrying blindly
}

When it happens

Trigger: connect() against an unreachable or misconfigured sync URL; auth rejected during a sync operation; BUSY (4) when the sync engine contends with another connection; an interrupted operation during teardown.

Common situations: Bad or missing url/authToken passed to connect(); serverless endpoint offline or returning errors the engine maps to 127; app backgrounding mid-sync causing interrupts; concurrent sync sessions.

Related errors

• push() is only available for sync databases
• pull() is only available for sync databases
• stats() is only available for sync databases
• checkpoint() is only available for sync databases
• Statement execution failed with status: ${result.status}

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/6bd1624b1066e7c0. Report an issue: GitHub.