Skip to main content

Error handling

Every failure is a typed rejection you can branch on. null means only "the key doesn't exist".

The contract​

const value = await icloudKV.getItem('k')
// null -> the key does not exist. Nothing else returns null.

Everything else rejects:

try {
await store.setItem('k', 'v')
} catch (e) {
e.code // ErrorCode
e.retryAfterMs // on ERR_RATE_LIMITED
e.limitBytes // on ERR_PAYLOAD_TOO_LARGE
e.actualBytes // on ERR_PAYLOAD_TOO_LARGE
e.serverErrorCode // the backend's own code, when there was one
e.provider // which provider raised it
}

Codes​

Codes map CloudKit's errors (framework, Web Services) and Drive's HTTP statuses; the original is kept on serverErrorCode. Per-provider details: CloudKit, Google Drive.

CodeMeaningTypical response
ERR_NOT_SIGNED_INNo account signed inPrompt sign-in
ERR_ACCOUNT_RESTRICTEDParental controls or MDMExplain; do not retry
ERR_ACCOUNT_UNAVAILABLEtemporarilyUnavailableRetry silently later
ERR_ACCOUNT_UNDETERMINEDStatus not yet knownDo nothing yet
ERR_AUTH_EXPIREDCredential expiredRe-auth
ERR_NETWORK_UNAVAILABLEOffline or unreachableQueue and retry
ERR_QUOTA_EXCEEDEDStorage fullTell the user
ERR_RATE_LIMITEDBacking off - including Drive's transient 5xxRetry after retryAfterMs
ERR_PAYLOAD_TOO_LARGEAbove the store's limitUse a bigger provider
ERR_INVALID_KEYKey cannot round-trip through the configured providers, an invalid CloudKit identifier (name, zone, record type, field), or a record of another type under the requested nameFix the key, or sanitizeKey it
ERR_TIMEOUTRan longer than the configured timeoutRetry; it may still be in flight
ERR_CONFLICTGoogle Drive holds several files for one key and onDuplicateName is 'error'Remove the extra files, or use the default 'newest'
ERR_CONTAINER_MISCONFIGUREDEntitlement, container, token or CloudKit permission (ACCESS_DENIED) problemFix the build or the Console
ERR_UNSUPPORTED_PLATFORMProvider unavailable hereBranch on isAvailable()
ERR_CANCELLEDCancelled by the callerNothing - they asked for it
ERR_UNKNOWNUnclassified; cause holds the original. serverErrorCode: 'UNTRUSTED_URL' means a URL was refused: a Drive URL outside googleapis.com, or a non-HTTPS CloudKit asset URLReport it

Notes:

  • ERR_INVALID_KEY fires before the request, instead of a confusing BAD_REQUEST (see keys).
  • ERR_TIMEOUT is an abandoned wait, not a failure.
  • ERR_CANCELLED comes from cloudKitAssets.cancel, cloudKitBackup.cancel, or an AbortLike signal passed to googleDriveFiles.

Classifying without a switch​

import { isCancelled, isRetryable, requiresUserAction } from 'react-native-cloud-sync'

try {
await store.setItem('k', 'v')
} catch (e) {
if (isCancelled(e)) return // they asked; say nothing
if (requiresUserAction(e)) promptUser(e.code) // signed out, out of storage
else if (isRetryable(e)) scheduleRetry(e.retryAfterMs)
else report(e)
}

Check isCancelled first: a cancellation isn't a fault. The facade's outbox already queues retryable failures, so most call sites need only requiresUserAction.

Recognising an error​

import { isCloudSyncError } from 'react-native-cloud-sync'

if (isCloudSyncError(e)) console.warn(e.code)

Use the guard, not instanceof: bridge rejections can arrive as plain objects, so it checks shape.

Distinguishing "absent" from "broken"​

let value: string | null = null
try {
value = await store.getItem('playlist')
} catch (e) {
// Reached the cloud and something went wrong. Do NOT treat this as
// "no backup exists" - that is how apps overwrite good remote data
// with an empty local state.
return showSyncError(e)
}

// Genuinely nothing stored yet, so seeding is safe.
if (value == null)
seedInitialState()

This works because the facade raises ERR_NOT_SIGNED_IN, never null, when no provider is reachable:

// One provider down, another up and holding the value -> the value.
// Every provider down -> ERR_NOT_SIGNED_IN, never null.