How to Prevent Duplicate Jobs or Imports in Home Assistant
Prevent duplicate Home Assistant jobs by making one logical operation identifiable and safe to retry. First prove where the second run starts; then control overlap, duplicate delivery, retries, and multiple-instance execution at the narrowest layer.
A repeated notification is annoying, but duplicate door, billing, irrigation, backup, or import actions can be harmful. Capture automation traces, trigger IDs, timestamps, operation inputs, and server identity before adding delays. The prevention design should reject the same operation key, allow genuinely new events, and recover cleanly if the first attempt fails halfway through.
Find the Exact Point Where the Duplicate Begins
Compare automation traces or job logs for the two executions. Record trigger platform, trigger ID, context, timestamp, input payload, run mode, retry count, and server identity. If two traces have different triggers, fix trigger overlap; if one trace performs the side effect twice, fix the action or import loop.
Home Assistant community troubleshooting shows that duplicate runs can be constrained with automation mode and timing, but it also warns that the underlying trigger should be understood. Use the duplicate-run trace pattern as a diagnostic direction, not a universal delay recipe.
Confirm that only one Home Assistant instance, scheduler, import container, or webhook consumer owns the job. If two servers share credentials or a queue, automation mode inside one instance cannot prevent cross-instance duplicates.
Choose the Prevention Boundary That Matches the Cause
For overlapping runs inside one automation, choose a run mode that matches the task: reject overlap for exclusive work, queue truly sequential work, or restart only when replacing the old run is safe. Do not use a mode change to merge distinct events that must all be processed.
For duplicate event delivery or retries, create an operation key from a stable event ID or a carefully chosen combination such as source, device, action, and time bucket. Store the last completed keys in a helper, database table, or import manifest with an expiry appropriate to the workflow.
For imports, enforce uniqueness at the destination when possible. Check and record the source item ID before writing, write atomically, and mark completion only after all required side effects succeed. A filename alone is weak if the same data can arrive under another name.
Make Retries Safe Instead of Disabling Them
A timeout does not prove the first attempt failed; the remote device or API may have completed the action before the response was lost. Before retrying, read the resulting state or query the destination for the operation key. Retry only when the intended state is absent.
Separate the claim step from the work step. One worker claims the operation key, performs the action, records success, and releases or expires a failed claim according to a documented rule. This prevents two concurrent containers from processing the same item while still allowing recovery after a crash.
The ZimaSpace explanation of Home Assistant background work after changes helps identify reloads, reprocessing, and downstream jobs that can look like duplicates but actually begin at different stages.
Test Duplicate Prevention Before Depending on It
Replay the same event twice, send two events close together, restart during the job, simulate a timeout after the destination commits, and briefly start a second worker in an isolated test. Each case should produce either one completed side effect or a clear queued second event when both are legitimate.
Verify the opposite boundary too: two genuinely different events must not collapse into one operation key. Check traces, destination records, device state, and the idempotency store so the prevention rule does not silently drop valid work.
If a duplicate already occurred, pause the producer, preserve traces and destination identifiers, reverse only side effects that are safe to undo, and repair the cause before replaying. Escalate integrations that emit duplicate event IDs or ignore documented run semantics with a minimal reproduction.
Recommended products
Support & Tips
More to Read
How to Optimize Home Assistant Database Connections for Concurrent Containers
Tune an external Recorder database from measured active connections and latency, not by raising max connections or copying another host's pool.
How to Repair Home Assistant After Its Database Volume Fills Up
Recover from a full Recorder volume without deleting evidence first, then reduce growth and prove history and automations survive restart.
Why Does Home Assistant Recreate Missing Files With the Wrong Owner?
Match the runtime UID and GID to the host path, repair only the affected files while stopped, and verify ownership after recreation.
