Skip to main content

Error Codes

The Swiftpatch SDK emits errors with stable, namespaced codes prefixed SWIFTPATCH_*. Every code is stable across minor versions — you can safely build dashboards, alerting rules, and user-facing error maps against them.

Detecting programmatically​

import { SwiftPatch, getKnownErrors, getErrorDescription } from '@swiftpatch/react-native';

// Static — safe to call before the Provider mounts
const codes = SwiftPatch.getKnownErrors();
// ['SWIFTPATCH_DOWNLOAD_FAILED', 'SWIFTPATCH_HASH_MISMATCH', ...]

// Human-readable recovery copy
const info = getErrorDescription('SWIFTPATCH_SIGNATURE_INVALID');
// { category, description, troubleshooting }

Subscribe to runtime errors via the event bus:

import { Swiftpatch } from '@swiftpatch/react-native';

Swiftpatch.onError((error) => {
  const { code, message, details } = error;
  const info = getErrorDescription(code);
  reportToSentry({ code, message, category: info.category });
});
CI check

Fail CI if your error-mapping table drops a code the new SDK started emitting:

const mapped = new Set(Object.keys(MY_USER_FACING_MESSAGES));
for (const code of SwiftPatch.getKnownErrors()) {
  if (!mapped.has(code)) throw new Error(`Unmapped SDK error: ${code}`);
}

Network / download​

SWIFTPATCH_DOWNLOAD_FAILED​

Generic download failure (DNS, TCP reset, TLS handshake). Fires when the bundle or patch URL cannot be fetched. Recovery Retry with backoff. The SDK retries automatically on the next resume check.

SWIFTPATCH_DOWNLOAD_HTTP_ERROR​

Server returned a non-2xx HTTP status. Fires when DownloadManager (Android) / URLSession (iOS) receives an error response code. Recovery Check the URL signature hasn't expired. If using a CDN, verify the release is published.

SWIFTPATCH_DOWNLOAD_EMPTY​

Downloaded file has zero bytes. Fires when the server responded 200 OK but the body was empty. Recovery Re-check the release upload on the server side.

SWIFTPATCH_DOWNLOAD_CANCELLED​

User or SDK called cancelDownload() while the transfer was in flight. Fires when a check is superseded by a newer one, or on component unmount. Recovery Usually not user-facing; surface as a progress-cancelled event.

SWIFTPATCH_RANGE_NOT_SUPPORTED​

Server refused a Range: resume request. Fires when the SDK tried to resume an interrupted download and the server responded without Accept-Ranges: bytes. Recovery The SDK falls back to a full re-download automatically.

SWIFTPATCH_NETWORK_UNREACHABLE​

No network connectivity. Fires when the JS layer detects NetInfo.isConnected === false before a check. Recovery Wait for connectivity and retry on appState === 'active'.

Signature / integrity​

SWIFTPATCH_HASH_MISMATCH​

SHA-256 of the downloaded bundle does not match the expected hash. Fires when the bundle has been truncated, corrupted, or tampered with. Recovery The SDK deletes the temp file and retries on the next check.

SWIFTPATCH_ARCHIVE_HASH_MISMATCH​

Zip archive hash (before extraction) does not match the manifest value. Fires when verifying the outer zip against the release manifest. Recovery Same as SWIFTPATCH_HASH_MISMATCH — retry.

SWIFTPATCH_FILE_HASH_MISMATCH​

A single file inside the extracted archive has an unexpected hash. Fires when manifest-level per-file hashes don't match the unpacked bytes. Recovery Delete the partially extracted slot and redownload.

SWIFTPATCH_FILE_SIZE_MISMATCH​

A file inside the archive has an unexpected byte length. Fires when zip-entry size disagrees with the manifest declaration. Recovery Treat as tampering; redownload and alert the SDK channel.

SWIFTPATCH_SIGNATURE_INVALID​

Ed25519 signature verification of the bundle or manifest failed. Fires when the signed payload does not validate under the configured publicKey. Recovery Verify the signing key on the server matches the SwiftPatchPublicKey configured in the app's Info.plist / strings.xml.

SWIFTPATCH_MANIFEST_INVALID​

manifest.json failed to parse or declares unsupported fields. Fires when the SDK cannot interpret the archive descriptor. Recovery The release was produced by an incompatible CLI/SDK pair — rebuild the release.

SWIFTPATCH_MANIFEST_MISSING​

manifest.json is not present inside the archive. Fires when the zip does not contain the manifest file. Recovery The release is malformed; re-publish it with a supported CLI.

SWIFTPATCH_TEMP_HASH_MISSING​

Pending bundle file referenced by state is absent on disk. Fires when iOS launches and the staged bundle has been purged (e.g. iOS wiped caches). Recovery SDK auto-clears pending state; a fresh download happens on the next check.

SWIFTPATCH_TEMP_HASH_CORRUPT​

Pending bundle hash on disk no longer matches its recorded hash. Fires when the staged file was truncated after staging (disk error). Recovery SDK purges the pending slot and refetches.

Patching (delta)​

SWIFTPATCH_PATCH_VERIFY_FAILED​

After applying a bsdiff patch, the output hash does not match the target. Fires when the base bundle used to patch wasn't actually the declared fromHash — base drift. Recovery SDK falls back to a full-bundle download automatically.

SWIFTPATCH_BSPATCH_FAILED​

bsdiff returned a non-zero exit code while applying. Fires when the patch stream is corrupt or truncated. Recovery Redownload the patch; if it persists, the CLI that produced the release has a bug — fall back to a full bundle.

SWIFTPATCH_BASE_MISSING​

Base bundle file the patch needs to apply against is not on disk. Fires when a patch is delivered for a bundle the device has never had. Recovery SDK requests a full bundle instead.

SWIFTPATCH_PATCH_OUTPUT_MISSING​

bsdiff completed but did not produce an output file. Fires when the bsdiff process exits 0 but the output path is empty (filesystem failure). Recovery Retry; escalate to full-bundle if repeated.

Slot / filesystem​

SWIFTPATCH_DISK_FULL​

Not enough free disk for download + extraction. Fires when writing to the staging directory fails with ENOSPC. Recovery Surface a user-facing prompt to free disk space. SDK will retry on next resume.

SWIFTPATCH_SLOT_CORRUPT​

An existing slot directory has inconsistent metadata. Fires when the slot manager detects missing files referenced by prefs. Recovery SDK wipes the slot and re-downloads the stable bundle.

SWIFTPATCH_UNZIP_FAILED​

Zip extraction failed (generic). Fires when the unzip library errors mid-stream. Recovery Delete staging dir and retry.

SWIFTPATCH_ZIP_SLIP​

A zip entry path escaped the extraction root (path traversal). Fires when an archive contains ../ style entries. Recovery The archive is malicious or misbuilt — discard it and alert.

SWIFTPATCH_COMMIT_FAILED​

Atomic rename of the staging directory into the final slot failed. Fires when filesystem permissions or cross-device rename blocks the swap. Recovery Retry; if persistent, the app sandbox is in a bad state — reinstall the app.

SWIFTPATCH_FILE_MISSING​

A file expected by the manifest is missing from the extracted archive. Fires when manifest references index.android.bundle but it's absent. Recovery Release is malformed; re-publish.

Runtime / state​

SWIFTPATCH_BUSY​

A conflicting operation is already in flight. Fires when two downloadUpdate calls collide, or stabilize runs during install. Recovery Wait for the current operation's promise to resolve and retry.

SWIFTPATCH_BLOCKED_HASH​

Requested hash has been blocklisted (rolled back from earlier). Fires when an app tries to re-install a bundle that has been marked bad. Recovery Fetch a newer release; do not retry the same hash.

SWIFTPATCH_ALREADY_APPLIED​

Pending bundle matches the currently running bundle. Fires when the JS layer calls installUpdate for a no-op hash. Recovery Treat as success — already on the target version.

SWIFTPATCH_NO_PENDING_INSTALL​

confirmInstall() was called without a staged update. Fires when there is no bundle in the NEW slot to promote. Recovery Run a check + download first.

SWIFTPATCH_NATIVE_VERSION_MISMATCH​

Native SDK version does not match the release's minimum native version. Fires when an OTA update requires a newer native binary than the app ships. Recovery Prompt the user to update via the app store; skip the OTA.

SWIFTPATCH_NO_BUNDLE_TO_STABILIZE​

stabilize() called but the NEW slot is empty. Fires when the JS layer invokes stabilize after a rollback already cleared it. Recovery No-op; log at debug level.

SWIFTPATCH_NOT_INITIALIZED​

SDK was used before init() resolved. Fires when a method on SwiftPatch is called before configuration. Recovery Always await sp.init() before other methods.

Config / auth​

SWIFTPATCH_INVALID_DEPLOYMENT_KEY​

Configured deployment key was rejected by the server. Fires when the check API returns 401/403 citing the key. Recovery Verify SwiftPatchDeploymentKey / swiftpatch_deployment_key in your native config. Rotate the key in the dashboard if compromised.

SWIFTPATCH_INVALID_ENVIRONMENT​

switchEnvironment() got an unknown value. Fires when the caller passes anything other than PROD or STAGE. Recovery Use the EnvironmentMode enum from the SDK.

SWIFTPATCH_JWT_EXPIRED​

Signed URL or auth JWT in the release descriptor has expired. Fires when download starts after the URL TTL has elapsed. Recovery Re-run the check to receive a fresh signed URL.

SWIFTPATCH_CONFIG_INVALID​

A required field in initialize() is missing or malformed. Fires when deploymentKey is empty, or serverUrl is not a valid URL. Recovery Fix the config passed to withSwiftPatch / SwiftPatchProvider.

Next steps​

On this page