Launched:self-serve migrations intoSuperhuman Docs (Coda)
Try it now
01Agent-first
Runs where you already work
Plug it into Claude, ChatGPT or Cursor. Describe the move in plain English; the agent runs it.
02Engineer-led
Our production engine, unlocked
The pipeline our engineers use on managed enterprise migrations — the same code, now something you can drive yourself.
03Pricing
Try 10 pages free, then $1 a page
Credit-based, pay-as-you-go. No scoping call, no quote — sample it on your own docs before you spend anything.
04Sources
NotionSlabConfluenceSoonGoogle DocsSoon
Skip to content

AI Migration Went Wrong? The Engineer's Triage Guide

An AI agent left a migration half-finished? Stop the writes, measure the damage, find duplicates and missed records, then decide whether to resume, patch or restart clean.

Rishabh Makhar Rishabh Makhar · · 17 min read
AI Migration Went Wrong? The Engineer's Triage Guide
TALK TO AN ENGINEER

Planning a migration?

Get a free 30-min call with our engineers. We'll review your setup and map out a custom migration plan — no obligation.

Schedule a free call
  • 1,500+ migrations completed
  • Zero downtime guaranteed
  • Transparent, fixed pricing
  • Project success responsibility
  • Post-migration support included

AI Migration Went Wrong? The Engineer's Triage Guide

If an AI agent, or a script an agent wrote, stopped mid-migration and the destination is half-loaded, here is the triage sequence. Do not let the run continue, and do not re-run the script. The next ten minutes decide whether this is a recoverable mess or a week-long cleanup.

The model is rarely the root cause. A migration is a bulk, one-time job that is hard to reverse, and vendor MCP servers are built for conversational work on a few records at a time. What the run lacked was a migration engine and someone accountable for the result. Our 2026 guide to AI agent migrations through MCP explains why. This guide covers what to do now: containment, damage assessment, and the decision to resume, patch, or delete and restart.

Info

Vendor behaviour cited below was verified against each vendor's own documentation on 17 November 2026. Check the linked pages before you run a cleanup.

Step 1: Stop all writes and revoke the run's credentials

First, stop the run from doing anything else. Every additional write makes the cleanup harder and the blast radius wider.

Kill the process running the script. Then revoke or rotate every credential the run used in the source and the destination. If it connected with an API key, rotate the key. If it used OAuth, revoke the access token and the refresh token. In Salesforce, freeze or deactivate the integration user. In HubSpot, rotate the private app's access token.

Do not rely on closing the terminal or stopping the MCP (Model Context Protocol) client. A background job, CI runner or reverse sync may still be running. Revoking the credentials is the dependable way to cut off access. Treat any credential powerful enough to create bad data as compromised until the cleanup is done.

Queued work: Revoking credentials stops new writes from the run. It does not cancel webhooks or sync jobs that the destination has already queued for other systems. Check the webhook delivery logs and pause those subscriptions directly.

Do not re-run the script to "finish what it started." A half-completed run left the destination in an unknown state. Running the same script again, without knowing what succeeded and what failed, compounds the damage.

Step 2: Freeze automations in the destination

Partially imported records look like new activity. If the run used standard create endpoints instead of import APIs, the destination treats the records as live work. SLA timers start, routing rules assign tickets, and customer-facing email triggers can fire on historical records.

Zendesk warns that tickets created with its normal bulk create endpoint "may be affected by your business rules," which can include emailing end users (developer.zendesk.com). Its Ticket Import API is the path built for history: triggers won't run on a ticket imported with a status other than closed, and CC'd users get no notifications (developer.zendesk.com). If the run used the normal endpoint, assume business rules ran.

Disable now:

  • Triggers and automations in the destination (Zendesk triggers, HubSpot workflows, Salesforce flows)
  • Outbound email sending, suppressed at the platform level if possible
  • Connected tools that react to new records (Slack integrations, webhook listeners, billing systems)

Step 3: Snapshot both systems before touching anything

Before you delete, patch or re-import a single record, export the current state of both systems. If you start deleting records first, you destroy the evidence you need to work out which records the run damaged.

Source system: A full export through the API or the admin console. Confirm the export includes archived and soft-deleted records, because default list endpoints often skip them.

Destination system: A full export of every object the run touched. This is your forensic baseline.

Also keep the run's logs, prompts, job IDs and timestamps, the API user or service account used for writes, and the list of automations you paused. Store snapshots outside both platforms, in storage with write-once retention if you have it. They are your insurance against mistakes during the cleanup.

Why agent migrations fail: a failure taxonomy

Before you triage, identify the type of failure. Each one points to a different recovery path.

Failure type Symptoms Triage path
Rate limit exhaustion Script stopped mid-run, 429 errors in logs, records cut off at a round number Find the last committed record, then resume with backoff
Auth expiry mid-run 401 errors after N records, inconsistent re-authentication Audit writes per auth session, check for duplicates created around the re-auth
Wrong or invalid field names Required fields left empty, values written to the wrong destination fields Full field-level audit, then patch or restart depending on scope
Pagination logic error Record count suspiciously low, gaps in IDs or timestamps Rebuild the gaps from the source, re-import the missed pages
Schema mismatch Type errors, truncated strings, broken picklist values Validate fields against the destination schema, patch affected fields
Lost session state Run restarted from scratch and created duplicates, no crosswalk saved Deduplication pass, rebuild the crosswalk from fingerprints
Inconsistent null handling Generated code or prompts changed between runs, so nulls were written differently (empty string in one batch, omitted field in another) Find records with blank required fields, patch from the source

Separate the planning from the execution. The agent plans the work and decides which calls to make or which code to write. The generated script, if there is one, makes the API calls. A planning error, such as a wrong field name or the wrong endpoint, needs a mapping fix. An execution error, such as a rate limit or expired auth, needs an operational fix. Treat them separately.

How do you identify every record the run created?

Blast radius isolation means finding every record the run touched. Three filters narrow it down:

  1. The API user or service account. Most platforms record which user created each record, for example Salesforce's CreatedById (developer.salesforce.com). Filter by the integration user the run authenticated as.
  2. The time window. Filter for records created or modified between the run's start and the moment it stopped.
  3. Tags or markers. If the script added a migration tag (for example migrated or import-batch-1), use it. Many improvised scripts do not add one, so you may have only the first two filters.
SELECT id
FROM destination_object
WHERE created_by = :api_user
  AND created_at BETWEEN :run_start AND :run_end
  AND (migration_tag = :run_tag OR import_job_id = :job_id)

One caveat: if the script used an import endpoint or audit-field permissions, the business created_at or CreatedDate may show source history, not the time of the bad run. In that case, rely more on the API user, audit logs and explicit tags than on business dates.

Build this inventory per object type: contacts, companies, tickets or cases, notes, attachments and custom objects. You need these counts for the scoring below.

Blast radius scoring: minor, significant or critical?

Damage is not binary. Use this rubric to set a severity tier before you choose a recovery path.

Minor (patch candidate):

  • Fewer than 5% of records affected
  • Damage confined to non-relational fields (text, dates, custom fields)
  • No live user work in the destination yet
  • No customer-facing emails triggered
  • Crosswalk intact or rebuildable

Significant (patch with risk):

  • 5 to 30% of records affected
  • Some relationship fields damaged (associations, ownership, parent-child links)
  • Limited live user activity in the destination
  • Some automations fired, but no confirmed customer-facing emails

Critical (delete and restart):

  • More than 30% of records affected
  • Core relationships broken (contacts linked to the wrong accounts, tickets attached to the wrong organizations)
  • Cascading deletes executed or at risk
  • Customer-facing emails confirmed sent on historical records
  • No intact crosswalk, and fingerprint reconstruction is ambiguous

Apply the rubric per object type, not to the migration as a whole. A migration can be minor for contacts and critical for associations at the same time.

Count records per object in source and destination

Do not settle for one grand total. Record-count parity is the fastest signal of how much transferred and how much is missing or duplicated. Count every object that matters: tickets, contacts, companies, conversations, notes, attachments, tasks, comments, associations and custom objects. Split the counts into active, archived and deleted buckets where the platform supports it.

For each object type, compare:

  • Source count: every record that should have migrated, including archives
  • Destination count: every record the run created
  • Delta: missing, extra or matched

A migration can look close at the headline level and still miss whole object classes. Matching 100,000 top-level records means little if 12,000 attachments, 8,000 associations or one archived pipeline of tickets never arrived.

A chat message saying "migration complete" is not a count. The evidence is a query against the destination, per object, compared with the source.

How do you find duplicates created by retries?

Retries without idempotency are the most common source of duplicates in agent-run migrations. Group destination records by a natural fingerprint (external ID, normalized email, normalized domain, subject plus requester) and inspect near-duplicates around the failure window.

Zendesk. Ticket creation accepts an Idempotency-Key header, so a retry with the same key does not duplicate a ticket. Keys expire after two hours, and a duplicate key sent after that creates a new ticket (developer.zendesk.com). If the run crashed and restarted hours later, or never sent a key, retried creates produced duplicates. Search for tickets with the same subject and requester created close together. The Bulk Delete Tickets endpoint (DELETE /api/v2/tickets/destroy_many?ids={ids}) accepts up to 100 ticket IDs per request. Deleted tickets are soft-deleted first: the List Deleted Tickets endpoint covers tickets deleted in the past 30 days, a deleted ticket can be restored, and permanent deletion cannot be undone (developer.zendesk.com).

HubSpot. HubSpot deduplicates contacts by email address. It says companies created through the API "will not be deduplicated by the Company domain name property," and that this includes third-party sync apps (knowledge.hubspot.com). If the run created companies through the API, expect a duplicate for every company that already existed. Group companies by normalized domain and merge them.

Salesforce. If the load inserted records instead of upserting by an external ID field, a retry inserted them again (developer.salesforce.com). Group by a natural key to find them, for example SELECT Name, COUNT(Id) FROM Account GROUP BY Name HAVING COUNT(Id) > 1. For large volumes, run the cleanup through Bulk API 2.0, Salesforce's documented path for large data jobs (developer.salesforce.com).

ID crosswalk reconstruction

The ID crosswalk, the map from source record IDs to destination record IDs, is the most important artifact of any migration. An improvised agent run often holds it only in session state, if anywhere. If the session is gone, here is how to rebuild it.

Method 1: External ID matching. If the run populated an external ID field on destination records, join source and destination on that field. Many improvised runs skip this step.

Method 2: Fingerprint matching. Define a natural key for each object type:

  • Contacts: normalized email address
  • Companies or accounts: normalized domain (strip www., lowercase, strip the trailing slash)
  • Tickets or cases: subject, requester email and source creation time (truncated to the hour to allow for timezone drift)
  • Notes or comments: author email, body hash and the parent record's fingerprint

Run the join against both exports. Records that match on fingerprint form your crosswalk. Flag near-matches (same subject, different requester) as ambiguous for manual review.

Method 3: The run's own logs. Every successful create call returns the new record's ID. If the run logged its requests and responses, pair each source record in the log with the destination ID in the response. Use this to confirm the matches from Method 2.

When reconstruction fails: If no method gives a confident match for a record, mark it unresolvable and keep it out of any automated cleanup. Manual review is the only safe path for ambiguous records.

Did the run miss archived or soft-deleted records?

Default list calls skip archived and soft-deleted records. A run that paged through list responses and called it done almost certainly missed some of these:

  • Zendesk archives tickets 120 days after they close (support.zendesk.com). "Archived tickets are not included" in the list tickets responses, and Zendesk recommends the Incremental Ticket Export endpoints to get every ticket (developer.zendesk.com). Incremental exports are limited to 10 requests per minute, or 30 with the High Volume add-on (developer.zendesk.com).
  • Salesforce returns records soft-deleted by a merge or delete, and archived task and event records, through the QueryAll resource. The Query resource does not. Once records are permanently removed from the Recycle Bin, QueryAll cannot return them either (developer.salesforce.com).
  • HubSpot says archived CRM objects won't appear in any search results (developers.hubspot.com). The same search is limited to 10,000 total results for any query, so a search-based export of a large account also stops short.

The run probably reported a count lower than reality. Compare the source system's totals, including archives, with what was actually exported.

Did the run break attachments with expired URLs?

Two expiry windows cause most attachment loss. Source files are often served from short-lived URLs: Notion-hosted file URLs expire after one hour (developers.notion.com). Destination uploads have their own window: a Zendesk upload token must be attached to a ticket within 60 minutes (developer.zendesk.com). If the run copied file URLs instead of downloading the files, the destination holds links that no longer work.

To audit, query every destination record with an attachment field populated, then send a HEAD request to each URL. Any response other than 200 marks a broken attachment. Fetch the file again from the source, with a fresh URL from the source API, and re-upload it to the destination.

What emails and automations already fired?

This is the damage a delete button cannot undo. If the run created records through standard endpoints rather than import endpoints:

  • Customers may have received notification emails about tickets or cases from years ago
  • SLA clocks may have started on historical records
  • Assignment notifications may have gone to agents
  • Connected tools (Slack, PagerDuty, billing systems) may have reacted to the "new" records

Audit what fired. Check outbound email logs, automation run histories and webhook delivery logs in the destination. If customer-facing emails went out, list the affected customers. A short, honest message is far better than hoping nobody noticed.

Warning

An email sent by a triggered automation cannot be recalled by deleting the record that triggered it. If the run used a standard ticket creation endpoint instead of an import API, check your outbound email logs now.

Should you resume, patch, or delete and restart?

With the blast radius scored and the damage assessed, you have three options.

Warning

Do not hand the cleanup back to an unattended agent run. An AI assistant can draft the cleanup script, and that is a good use of it. A person reviews the script, runs it against a sample, and then runs it as code with a log of every record it touches. Errors that compound across an unattended cleanup are how a messy load turns into lost data that someone has to answer for.

Path Choose when Avoid when
Resume Blast radius is minor, the mapping was correct, the failure was operational (timeout, rate limit), and the last good write is provable from an intact or rebuildable crosswalk You cannot prove what committed, retries are not idempotent, or the failure was a wrong mapping or schema mismatch
Patch Blast radius is minor to significant, most records transferred correctly, the bad set is enumerable and confined to specific fields, and users are already active in the destination The damage touches core relationships, system fields, or more than 30% of records
Delete and restart Blast radius is critical, the destination is lightly used, the source is intact, and the crosswalk is rebuildable or will be rebuilt from scratch New live work is mixed with migrated data, the cascade risk is unknown, or the Salesforce Recycle Bin's 15-day window will close before you can check the result

Rate limits during cleanup: Deletes and patches count against the same API limits as the original load. Zendesk's Support API allows 200 requests per minute on Team, 400 on Professional, 700 on Enterprise and 2,500 with the High Volume add-on (developer.zendesk.com). Throttle cleanup scripts well below the ceiling to leave headroom for live traffic.

Once users are working in the destination, delete-and-restart gets more expensive by the hour. New live records mix with migrated data and can no longer be dropped safely with the bad batch.

Why deletion cascades are dangerous

Deletion is the highest-risk option. In Salesforce, deleting a master record in a master-detail relationship also deletes all of its detail records (developer.salesforce.com). If the run linked detail records to the wrong master, deleting that master deletes every detail record attached to it, including valid records that were there before.

The Salesforce Recycle Bin keeps deleted items for 15 days, and they can be restored there with Undelete during that time. After 15 days Salesforce schedules them for permanent deletion, and a permanently deleted item cannot be recovered from the Recycle Bin (help.salesforce.com). Salesforce's hosted MCP server has no undelete tool, so a restore happens outside the MCP server (developer.salesforce.com). Plan on your own backup for anything outside that window.

Danger

Before you bulk-delete records in Salesforce, map every master-detail and lookup relationship on the objects you are targeting. Delete child records first, then parents. Run the delete in a sandbox with equivalent data first if you can. Verify your backups before you run any bulk delete.

Why the restart must come from a frozen mapping and a sample

The instinct after a failed run is to fix the prompt, adjust the script and try again. That is how teams end up with two half-finished migrations and a worse cleanup.

A proper restart needs:

  1. A frozen, reviewed field mapping. Every source field mapped to a destination field, with transformation rules written down and signed off. A mapping generated afresh on each run can drift between runs. Anthropic notes that model output is not fully deterministic even at temperature 0 (platform.claude.com). The mapping has to be a file a person approved, reused unchanged.

  2. A sample migration first. Run 50 to 500 records before anything else moves. Check by hand that original creation dates survived, authors are right, associations are intact and no automations fired. Include edge cases: attachments, inline images, deeply nested comments and records with empty required fields.

  3. The correct endpoints. Use the paths each platform provides for historical data:

    • Zendesk: Use the Ticket Import API, not the normal create endpoint. It sets created_at, updated_at and solved_at, accepts up to 100 tickets per request, and does not run triggers on tickets imported with a status other than closed (developer.zendesk.com).
    • Salesforce: Audit fields such as CreatedDate and CreatedById can be set only on insert, when the org enables "Set Audit Fields upon Record Creation" and the loading user has that permission (developer.salesforce.com). Upsert by external ID so a retry updates instead of inserting (developer.salesforce.com).
    • HubSpot: The Create date property is read-only for every object except deals (knowledge.hubspot.com). Associations need the IDs of both records, so load parents before children (developers.hubspot.com).
  4. Idempotent loads by external ID. Every record carries its source-system ID, so a retry updates instead of duplicating. Without it, any interruption and re-run produces duplicates.

  5. Parent-before-child load order. Organizations before users. Users before tickets. Accounts before contacts before opportunities. Save the ID crosswalk outside the session, to a file or a database table, before the next object type starts loading.

  6. Deterministic execution. The migration runs from code that does the same thing every time. Transfer directly API to API where possible, then structured JSON or NDJSON, with CSV last, because CSV cannot represent nested relational data or the difference between null and an empty string.

Tip

A reviewed sample is not busywork. It is where you catch missing archived data, bad dedupe rules, broken authorship and side effects before they multiply across the whole dataset.

Where AI genuinely helps in the recovery

None of this means taking AI out of the work. It means putting AI where a person can check its output.

  • Drafting the inventory and dedupe queries. An assistant can write the SQL or SOQL above for each object type. A person runs it and checks the results.
  • Writing the fingerprint-matching code. Anthropic's engineering team recommends that agents process large data in code outside the model, rather than passing records through tool calls (anthropic.com). The script does the join, and the model never reads 100,000 rows.
  • First-draft mappings for the restart. The dlt team migrated HubSpot to Attio with an AI drafting the model, transforms and tests while people reviewed every change. A human caught a proposed design that conflicted with GDPR deletion rules (dlthub.com).
  • Spot checks on a sample. Quandri's team used an LLM to write data adapters over about 40 iterations, with a domain expert reviewing. They note that a score cannot see a value placed in the wrong field (quandri.io). Sample review stays a human job.

The shape is the same each time: AI drafts, a person reviews, deterministic code runs the job.

The compliance and audit risk

A failed migration is also an audit question. An auditor will ask who had access to the data, under what contract, what moved, what did not, and how you know the destination matches the source. Under GDPR Article 5(2), the controller must be able to demonstrate compliance with the data protection principles (gdpr-info.eu). If triggered emails or automations sent personal data to the wrong people, assess that with your data protection lead.

A chat transcript ending in "migration complete" is not that evidence. The evidence is record counts per object, rejected records with reasons, field-level checks, the authorization for the credentials used, and a sign-off. If the run skipped these, rebuild them as part of the rescue.

Platform-specific gotchas: side-by-side reference

Issue Zendesk HubSpot Salesforce
Retry safety Idempotency-Key on ticket creation, keys expire after two hours (developer.zendesk.com) API-created companies not deduplicated by domain, import rows without email or Record ID become new records (knowledge.hubspot.com) Upsert by external ID (developer.salesforce.com)
Records default calls miss Archived tickets left out of list endpoints, use Incremental Ticket Export (developer.zendesk.com) Archived objects never appear in CRM search (developers.hubspot.com) Soft-deleted records need QueryAll (developer.salesforce.com)
Original dates Ticket Import API sets created_at, updated_at, solved_at (developer.zendesk.com) Create date read-only except on deals (knowledge.hubspot.com) Audit fields on insert only, with the Set Audit Fields permission (developer.salesforce.com)
Side effects Normal creates may run business rules and email end users (developer.zendesk.com) Review active workflows before any re-run Deactivate validation and assignment rules before a large load (trailhead.salesforce.com)
Bulk delete and undo destroy_many takes 100 IDs per request, soft-deleted tickets can be restored, permanent deletion cannot be undone (developer.zendesk.com) The HubSpot MCP server has no CRM delete tool (developers.hubspot.com) Recycle Bin for 15 days, no MCP undelete tool, master-detail deletes cascade (developer.salesforce.com)

When to bring in a migration engineer

If the blast radius is critical, the crosswalk cannot be rebuilt, or customer-facing emails have already gone out on historical data, the cleanup is a project of its own.

ClonePartner takes over failed migrations, including ones left by AI agents and DIY scripts. A dedicated migration engineer owns the project. The data moves through a deterministic migration engine, not a general-purpose AI agent: fields are copied from source to destination without a language model reading customer records.

The process is the same whether you are starting fresh or rescuing a half-finished run:

  1. Connect accounts and agree a migration checklist
  2. Run sample migrations on your real data until the mapping is right (unlimited, included in the price)
  3. Freeze the field mapping after you review the sample
  4. Run the full migration from that same frozen mapping
  5. Close with a delta sync of the records that changed during the migration window

After the data moves, you get a reconciliation report: record-count parity per object, field-level validation, referential integrity checks and checksums. Each project has one fixed price, starting at $500, with no hourly billing and no change orders.

If your incident is about support data, read the engineer's rescue guide for failed help desk migrations. If users are already working in the destination, pair this guide with how to roll back a failed migration after go-live.

Frequently Asked Questions

What is the first thing to do if an AI data migration fails?
Stop all writes. Revoke or rotate every API token and credential the run used, because closing a terminal does not stop background jobs or queued retries. Then pause triggers and automations in the destination, so partially imported records do not email customers or start SLA timers. Export both systems before you change anything.
Why do AI agents create duplicate records during a migration?
Because a retry repeated a create call that had already succeeded. Zendesk's Idempotency-Key header for ticket creation expires after two hours, so a retry after that window creates a new ticket. HubSpot says companies created through the API are not deduplicated by the Company domain name property. In Salesforce, a load that inserted records instead of upserting by an external ID inserts them again on a retry.
Can I use the AI agent to write a cleanup script for a failed migration?
It can draft one, and that is a reasonable use of it. Do not let it run the cleanup unattended. A person reviews the script, runs it against a small sample first, and then runs it as code with a log of every record it touches. The same rule applies to the restart. AI drafts, a person reviews, and deterministic code runs the job.
Can I undo a Salesforce bulk delete done during migration cleanup?
For 15 days, yes. Deleted records stay in the Recycle Bin for 15 days, and they can be restored there with Undelete. After that Salesforce schedules them for permanent deletion, and a permanently deleted item cannot be recovered from the Recycle Bin. Salesforce's hosted MCP server has no undelete tool. Deleting a master record in a master-detail relationship also deletes all of its detail records.
What records do AI migration scripts usually miss?
Archived and soft-deleted records. Zendesk archives tickets 120 days after they close, and its list tickets endpoint leaves archived tickets out. HubSpot's CRM search does not return archived objects. Salesforce returns soft-deleted records only through QueryAll. If the run read only the default set, its counts and its "done" message were wrong from the start.

More from our Blog

How to Roll Back a Failed Migration After Go-Live
From The Migration Trenches

How to Roll Back a Failed Migration After Go-Live

Rollback is harder than the original migration and often impossible after 72 hours. This guide covers triage, three rollback patterns, and platform-specific constraints for reversing a failed SaaS migration.

Nachi Raman Nachi Raman · · 17 min read