Resolve sync conflicts

A conflict means the same entity or synced file changed both in your local checkout and in the cloud (Setup UI, the assistant, the API, or another checkout) since your last pull. Everything else merges on its own: hmi pull takes server changes to things you did not touch and keeps your changes to things the server did not touch.

Related pages: Synchronize local changes, About local sync, CLI reference.

When conflicts appear

• hmi pull keeps your local version of every entity and file you changed. If the server also changed or deleted it, pull records the server version as a conflict and prints how many exist. An identical change on both sides is not a conflict.
• hmi push fails with push_conflict when any entity or file it changes was changed or deleted on the server since your last pull, and nothing is applied. The details after the code list the entities and files; see Push errors.

Push refuses while conflicts recorded by a pull are still unresolved. hmi push --dry-run still works, so you can review what would be sent.

Report comments are create-only and never conflict. The workspace name has no conflict detection; the last push wins. Pushing a new name, or a changed logo or favicon, needs an admin or owner (push_admin_required).

Recover from a rejected push

pnpm hmi pull        # keeps your changes and records the conflicts
pnpm hmi status      # lists them
pnpm hmi resolve …   # settle each one (see below)
pnpm hmi push

List conflicts

pnpm hmi status

Besides local changes and revisions, status prints conflicts: N and one line per conflict:

conflicts: 2
  parameter 5b0c…e1 (changed on server)
  file src/dashboards/9f3a…/index.tsx (deleted on server)

Inspect the server version

To see what changed on the server, open the entity in the cloud app. Pull also keeps the server version of each conflict in setup.db; the CLI has no separate command to show it, so read it with hmi sql:

pnpm hmi sql "SELECT remote_payload FROM entity_conflict WHERE entity_id = '<id>'"
pnpm hmi sql "SELECT CAST(remote_content AS TEXT) FROM file_conflict WHERE path = '<path>'"

NULL means the server deleted that entity or file.

Decide per conflict

Choose exactly one side:

Flag	Effect
--ours	Keep your local version (or your local deletion). The next hmi push replaces the server version. If the server deleted the entity and you keep yours, the push creates it again.
--theirs	Replace your local version with the server’s, or delete it locally when the server deleted it. For files, the server content is written to disk.

pnpm hmi resolve parameter <id> --theirs
pnpm hmi resolve dashboard <id> --ours
pnpm hmi resolve file src/dashboards/<id>/index.tsx --ours
pnpm hmi resolve --all --theirs

Entity types: dashboard, endpoint, edge_program, parameter_tree_branch, parameter, report_preset, report_comment, alarm_rule, automation. --all settles every conflict the same way; with --theirs, parents are written before their children and deleted after them. Taking the server’s deletion of one entity is refused while deleting it would also delete another with local changes, such as an automation of a deleted dashboard: resolve that one first, detach it, or resolve both with --all. Taking the server’s version also fails with a hint while other local entities still refer to the deleted entity, or when the server’s version refers to entities missing locally; resolve those first, or resolve everything together with --all.

To combine both sides, resolve with --ours, then edit the local row with hmi sql or the file on disk before pushing.

Push after resolving

Once hmi status shows conflicts: 0, run pnpm hmi push. Kept local versions are sent against the server’s current revision, so they no longer conflict unless the server changes them again. In that case, pull and resolve once more.

Start over instead

To drop local work entirely, hmi pull --discard-local replaces local setup and synced files with the server version and clears all conflicts. Back up first with hmi download --no-readings --no-const-values <file> if you may want to restore it with hmi upload <file>; see Back up and restore local changes.