Doctor

Overview

Use hot-updater doctor to check the parts that must agree for OTA updates to work:

• All Hot Updater packages use compatible versions
• React Native native files are connected to Hot Updater
• Your deployed infrastructure server is not outdated

Run it after upgrading Hot Updater, or when OTA updates behave differently after a package update.

npx hot-updater doctor

In an interactive terminal, the command asks for your server base URL. Press Enter to skip the server check.

For AI agents and other automation, use JSON output:

npx hot-updater doctor --json

--json does not prompt for the server URL. Pass --server-base-url when you want the infrastructure check included.

To repair safe local metadata issues, run:

npx hot-updater doctor --fix

--fix loads your Hot Updater config and runs diagnostics hooks exposed by the active database adapter. For blob-style adapters, this can rebuild the management bundle index from canonical update.json manifests. The command checks the index again after repair and reports a failure if the index is still out of sync.

Check Native Setup

When @hot-updater/react-native is installed and native iOS or Android directories exist, doctor checks:

• iOS AppDelegate uses HotUpdater.bundleURL()
• Android MainApplication uses HotUpdater.getJSBundleFile(...)
• If updateStrategy is fingerprint, fingerprint.json exists and native fingerprint hashes match it
• Signing settings match native public key entries

If any required native setting is missing, rebuild-time OTA configuration is not healthy yet. Run the command shown by doctor, then rebuild the native app.

doctor does not require a default channel in native files. If HOT_UPDATER_CHANNEL or hot_updater_channel exists, the command reports it as context only.

For fingerprint projects, fix missing or stale native fingerprint settings with:

npx hot-updater fingerprint create

AI Agent Iteration

doctor --json returns structured issues that an agent can use without parsing human-readable terminal output.

Each native issue includes:

• code: stable issue code, such as MISSING_ANDROID_BUNDLE_PROVIDER
• platform: ios, android, or project
• paths: related local files when available
• fixability: whether the issue is suitable for an agent loop
• commands: safe local commands when the fix is command-driven

Use fixability as the automation boundary:

Native wiring, fingerprint creation, and native public key export/removal are intended to be iterated locally by an agent. Infrastructure failures are marked as blocked because applying migrations or redeploying a server usually depends on provider credentials and environment-specific access.

Bundle index repair is only available when the active database adapter exposes diagnostics hooks. Adapters without those hooks report not-applicable.

Check Infrastructure

To check the deployed server in CI or a non-interactive shell, pass the public update-check base URL.

npx hot-updater doctor --server-base-url https://updates.example.com/api/check-update

doctor appends /version and checks:

https://updates.example.com/api/check-update/version

Example success output:

Checking the health of Hot Updater.
hot-updater CLI version: x.x.x
Server version endpoint: https://updates.example.com/api/check-update/version
Server version: x.x.x
Required infrastructure version: x.x.x
✅ Server infrastructure is up to date.
✅ All Hot Updater checks passed!
Doctor check complete.

Update Package Versions

If doctor reports version mismatches, update every Hot Updater package in package.json to the same compatible version, then run your package manager install command.

Update Outdated Infrastructure

If your server is outdated, doctor prints:

Infrastructure update required. Deploy server infrastructure version x.x.x or newer.

How to fix it depends on how you run Hot Updater:

• Self-hosted server using createHotUpdater: update all Hot Updater packages together, including @hot-updater/server, then redeploy your server.
• Managed providers (aws, cloudflare, supabase, firebase): run npx hot-updater init again and redeploy the generated provider infrastructure.

Options