Helpdesk Migration Failed? The Engineer's Rescue Guide

If your helpdesk migration just failed — data is missing, tickets are corrupted, or your script stalled halfway through — stop everything. Do not re-run the failed job. Do not let agents work in the half-migrated target system. Every new ticket, every agent reply, every status change in either system right now is widening the gap between what you have and what you need.

This guide is a structured recovery plan for engineers dealing with a broken helpdesk migration. It covers emergency triage, root cause diagnosis, sandbox validation, delta migration for in-flight data, reconciliation checks, and a clear decision framework for when to roll back versus push forward. If you have already read our common helpdesk migration mistakes guide and still ended up here, you are not alone — most failed migrations share the same handful of root causes.

Emergency Triage Checklist: Stop the Bleeding

Do these five things right now, in order. Time matters.

1. Stop writes to the target system. Disable all inbound email routing, chat widgets, and API integrations pointing at your new helpdesk. If agents are already working in the new system, pause them. Every ticket created in the target during a partial migration makes reconciliation exponentially harder. If Intercom is the target, disable email notifications before importing historical tickets so you do not spam customers during recovery. (developers.intercom.com)

2. Re-route all traffic to the source system. Ensure all incoming emails, webhooks, and integrations are pointing to your old helpdesk. Your support team must continue working in the legacy environment until the data integrity issue is resolved. Until proven otherwise, the old helpdesk stays authoritative.

3. Export full backups from both systems. Pull a complete export from your source helpdesk using its API or built-in export. Then capture the target system's current state — ticket count, user count, last ticket ID, attachment status. Store backups outside both platforms: an S3 bucket, Google Cloud Storage, or a local drive.

4. Preserve migration logs and error details. Save request bodies, HTTP response codes, Retry-After headers, and any rate-limit metadata from the failed run. You need to know if you hit a 429 Too Many Requests, a 413 Payload Too Large, or a 422 Unprocessable Entity. These logs are the forensic trail that determines your recovery path. Intercom, Freshdesk, and Zendesk all expose rate-limit behavior in response headers that materially changes rescue design. (developers.intercom.com)

5. Disable automations and triggers on both sides. Automations in the target system — welcome emails, SLA timers, assignment rules — will fire on partially-imported data, creating noise that masks real problems. Zendesk notes that imported tickets do not run triggers and do not bring in ticket metrics like first reply time, so production behavior and imported history will not match unless you account for it. (support.zendesk.com)

Why DIY and Automated Helpdesk Migrations Fail

Most failed helpdesk migrations share one of four root causes. Understanding yours determines the recovery path.

API Rate Limits That Kill Extraction Scripts

The most common silent failure. Your script starts strong, then slows to a crawl or starts throwing 429 Too Many Requests errors.

Zendesk caps incremental export endpoints at 10 requests per minute on standard plans. With the High Volume API add-on, that increases to 30 requests per minute. DIY scripts that do not implement proper cursor-based pagination and exponential backoff will stall or silently drop pages of results. (developer.zendesk.com)

Intercom distributes its per-app limit of 10,000 requests per minute into 10-second windows — roughly 1,666 operations per 10-second period. If your script uses heavy concurrency and fires 2,000 requests in a 3-second burst, Intercom will immediately return 429 errors, even if total per-minute usage is well under the cap. This windowed rate limiting is one of the most common traps for DIY migration scripts. Intercom's native S3 exports also do not include conversation transcripts — to get the actual messages, you must use the REST API, forcing you to navigate these exact rate limits.

Freshdesk enforces account-wide limits plus per-endpoint sub-limits. On Growth plans, ticket creation is capped at 80 requests per minute.

For a deeper look at how AI-generated migration scripts specifically fail at these constraints, see why DIY AI scripts fail at data migration.

Structural Mismatches Between Platforms

Zendesk organizes data around tickets with discrete comments, side conversations, and audit trails. Intercom organizes around conversations with flat message parts. Freshdesk has its own object model with different attachment size limits and no native equivalent for Zendesk side conversations.

When a migration tool encounters an object that has no 1:1 mapping in the destination platform, it either drops the data or silently truncates it. This is not a bug — it is a design gap. A migration can report 100% ticket-count parity while missing 10–15% of the actual content agents need.

Missing Contact Dependencies

Helpdesk data is highly relational. A single ticket depends on a user record, an organization record, tags, custom fields, and attachments. If the contacts associated with your tickets are missing, corrupted, or out of sync, the ticket import will fail or stall.

Zendesk's Ticket Import API rejects tickets where the requester does not exist as an active user. Intercom's migration documentation states every migrated ticket or conversation must be associated with an existing user or lead. (intercom.com) This means your user import must complete cleanly before ticket migration begins.

Native Import Tool Limitations

If you tried using a platform's built-in CSV importer, you likely hit a wall fast. Zendesk's native CSV import handles users and organizations only — it cannot import tickets at all. Tickets require the Ticket Import API. Even then, handling multi-comment threads, inline attachments, and historical timestamps requires careful API orchestration that CSV files cannot express. A CSV import flattens your support history into a single text block stamped with today's date.

Automated tools like Import2 process at an average speed of ~50,000 tickets per day and do not support the import of agent profiles, macros, or saved replies. For straightforward migrations this works. For complex recoveries with partial data already in the target, it is not enough.

Intercom's own import tutorial notes that DIY API work is attractive for flexibility and cost control, but warns that large migrations need changes beyond the sample code. (developers.intercom.com)

Run a Sandbox & Sample Migration

Before you attempt to fix or resume the full migration, validate your approach in a safe environment.

Set Up an Isolated Sandbox

Most helpdesk platforms offer sandbox or trial instances. Create one. If your target is Zendesk, spin up a Zendesk Sandbox (available on Enterprise plans). For Freshdesk, use a free trial instance. For Intercom, create a test workspace.

Intercom's migration guidance explicitly calls for batch testing on a subset before the initial run, and that pattern is sound: fix mapping logic where failure is cheap, not after thousands of live records are wrong. (intercom.com)

What to Validate

Your sandbox migration should test for these specific behaviors:

• Thread direction and timestamps. Did the comments import in the correct chronological order? Do they retain their original creation dates, or did the API stamp them with the time of the import? Zendesk's Ticket Import API accepts created_at, updated_at, solved_at, and comment-level created_at. If you omit these, the record defaults to the import time. (developer.zendesk.com)
• Inline image rendering. Did the inline images transfer? If the source system requires authentication to view attachments, your script must download the image, upload it to the target, and rewrite the HTML <img> tags in the ticket body.
• Attachment integrity. Do PDFs, CSVs, and images download correctly? Check for size limits on the target platform.
• Public vs. private visibility. Verify that internal notes remained private and public replies show as customer-facing. A single mapping error here can expose internal communications to customers.
• Relational integrity. Is the ticket correctly assigned to the right user and organization? If a contact was missing, did the script fail or assign the ticket to a fallback user?

Sample Size That Actually Catches Problems

Do not test with 5 tickets. Use a minimum of 100 tickets selected across these categories:

• Tickets with 10+ comments (tests thread depth)
• Tickets with inline images in the body (tests HTML sanitization)
• Tickets with attachments >5MB (tests size limits on the target)
• Tickets in every status (open, pending, solved, closed)
• Tickets assigned to agents who no longer exist (tests edge-case handling)
• Tickets with nested custom fields and multiple tags
• Merged tickets and tickets with deleted users

Your sample set should be deliberately ugly. If a scenario exists in production, it needs to exist in the sample. Help Desk Migration's demo guidance also notes that failed records often come down to missing contact data or inactive agents. (help-desk-migration.com)

Maintain a Crosswalk Table

For every test run, keep a mapping between source and target IDs:

source_ticket_id     -> target_ticket_id
source_contact_id    -> target_contact_id
source_comment_id    -> target_comment_id or ordinal
source_attachment_id -> target_attachment_id
migration_batch_id   -> rollback/retry scope

A sample run is successful only if it is repeatable. Counts must match, authors and public/private direction must be correct, attachments must open, and a second run must not create duplicates. If you do not have idempotency yet, you do not have a rescue plan.

How to Capture In-Flight Data (Delta Migration)

While your migration was failing or stalled, your support team kept working. Customers kept submitting tickets. Agents kept replying. That in-flight activity exists in the source system but not in the target, and it needs to come across without creating duplicates.

Delta migration captures only the records created or updated since a specific timestamp — typically the moment your original migration began.

How It Works

1. Identify your cutoff timestamp. Find the exact Unix timestamp of the last successful record extracted before the crash, or use the start_time of your original migration run.

2. Use incremental export APIs. Zendesk's Incremental Exports API supports cursor-based pagination and returns only items changed since your start_time:

GET /api/v2/incremental/tickets/cursor?start_time=<unix_time>
GET /api/v2/incremental/ticket_events?start_time=<unix_time>&include=comment_events

In Zendesk, the initial start_time must be at least one minute in the past, and both ticket and ticket-event exports omit the most recent minute to avoid race conditions. If you need full comment bodies in the event stream, use include=comment_events. (developer.zendesk.com) Intercom's conversation search can be filtered by updated_after.

3. Deduplicate against the target. Before importing delta records, cross-reference against what already exists in the target system by source ticket ID or external ID. Your script must use upserts (update if exists, insert if not) rather than blind inserts. This ensures that if a ticket was partially migrated during the crash, the delta sync will overwrite it with the complete record instead of creating a duplicate.

4. Repeat until the delta window is small enough to cut over safely.

Pause notifications while the delta runs. Intercom explicitly tells teams to turn off email notifications for historical ticket imports. Zendesk imported tickets do not run triggers, but surrounding integrations or webhook-based syncs can still fire if you do not isolate them. (developers.intercom.com)

For the full pattern behind keeping support running during a migration, see zero-downtime helpdesk migration.

Timeline Reality Check

The longer the gap, the more complex the delta. If your source system accumulated a week of activity, you are not patching — you are running a second migration.

Validation & Reconciliation Checklist

After completing the rescue migration (sandbox-validated, delta-inclusive), run these checks before declaring victory. Do not rely on ticket counts alone — a script can successfully create 10,000 tickets while silently dropping every attachment.

Record Counts

• Total ticket count in target matches source (within migration scope)
• Total user/contact count matches
• Organization count matches
• Knowledge base article count matches (if migrated)

Compare counts by slice, not just totals. Break down by status, created month, team or group, and inbox or brand.

Content Integrity

• Thread depth: Open 20+ high-comment tickets and verify all comments appear in correct chronological order
• Inline images: Confirm screenshots and embedded images render (not just show as broken <img> tags)
• Attachments: Spot-check that PDFs, CSVs, and images download correctly. Zendesk drops attachments larger than 50 MB. (support.zendesk.com)
• Private vs. public: Verify internal notes did not flip to public-facing replies
• Author mapping: Verify that internal notes are attributed to the correct agents, not the API admin account that ran the script

Metadata Accuracy

• Timestamps: created_at and updated_at match source values
• Assignees: Tickets assigned to the correct agents and groups
• Custom fields: Dropdown values, text fields, and checkboxes transferred correctly
• Tags: All source tags present on target tickets
• Statuses: Open/pending/solved/closed map correctly (watch for platforms that do not support all states)

Relationship Integrity

• Requester → ticket: Every ticket has a valid requester
• Organization → user: Org memberships intact
• Parent → child tickets: If using linked or child tickets, verify relationships

Operational Object Parity

• Macros, saved replies, and triggers migrated where applicable. Import2 does not import agent profiles, macros, or saved replies into Zendesk. (import2.com)
• Workflow triggers: Confirm migrated tickets did not accidentally trigger automations (e.g., sending thousands of old satisfaction surveys to customers)
• Searchability: Agents can find migrated tickets by requester email, old ticket ID, and external ID during the first weeks after cutover

For the full 20-test QA suite, see our post-migration QA checklist.

Rollback vs. Continue: The Decision Framework

This is the hardest call. Here is a framework.

Choose ROLLBACK when:

• More than 30% of tickets have content-level issues (missing comments, broken attachments, wrong timestamps)
• Your target system has been actively used by agents for less than 48 hours (minimal new data to lose)
• The root cause is a fundamental mapping error that affects every record (e.g., all internal notes migrated as public)
• You used a native CSV importer and lost all thread history and timestamps
• The effort to write a script that patches the missing fields exceeds the effort of a clean re-migration

Choose CONTINUE + PATCH when:

• Fewer than 10% of tickets have issues, and the issues are identifiable and patchable
• Agents have been working in the new system for 3+ days (significant new data exists only in the target)
• The failure was a hard stop (e.g., a 429 rate limit crash) rather than silent data corruption — you know exactly which ticket ID failed
• The target platform supports idempotent upserts, allowing you to safely re-run without duplicating records
• You have a validated sandbox run proving the fix works

The gray zone (10–30% issues): The deciding factor is whether agents have started using the target system. If yes, rolling back means losing their recent work — that is often worse than patching. If no, roll back and do it right.

Be especially careful with attachment-heavy recoveries. In Zendesk, attachments are bound to new comments via single-use upload tokens and cannot be added to an existing comment after the fact. If historical attachment placement matters, rollback is often safer than trying to surgically repair in place. (developer.zendesk.com)

How to Roll Back

If you choose rollback:

1. Re-route all channels (email forwarding, chat, phone) back to the source system
2. Notify agents and set a clear "we are back on the old system" timestamp
3. Delete or archive the partially-imported data in the target — do not leave ghost records
4. Review and fix the root cause before attempting again
5. Run a fresh validated sandbox migration before scheduling the next attempt

Check deletion semantics before you promise a rollback window. Not all migrated data can always be deleted cleanly from every platform. (help-desk-migration.com)

When to Request a Managed Rescue

DIY recovery makes sense when the failure is contained — a few hundred missing attachments, a custom field mapping that needs adjustment, a rate-limit issue you can solve with better backoff logic.

But some situations call for a team that has done this before:

• You have attempted recovery twice and the same issues recur. Repeating the same approach without changing the underlying architecture will produce the same result.
• The volume exceeds what your team can validate manually. Spot-checking 20 tickets out of 200,000 is not validation — it is hope. Reconciliation at scale requires automated diff tooling.
• You are hitting platform-specific edge cases — multipart attachment uploads, HTML sanitization quirks, undocumented API behaviors — that your team has not encountered before.
• Live support cannot pause and you need delta-based recovery rather than a hard freeze.
• Source exports are incomplete and you need API-based rehydration of threads or comments.
• Compliance or audit requirements mean approximate history is not good enough.

At ClonePartner, we step into stalled migrations and take full accountability for the outcome. Our engineers write custom scripts tailored to the exact source and target schemas, handle the undocumented edge cases (rate-limit windowing, inline image re-hosting, side conversation conversion), and run continuous delta syncs so your support team never has to stop working. We typically scope a rescue engagement within 24 hours of the first call and execute recovery in days, not weeks.

Estimated Recovery Timelines

These assume the source system is still accessible and a backup exists. If the source system has been decommissioned or the backup is incomplete, add time for data reconstruction.

Timelines stretch fast when APIs are tight. Zendesk incremental exports are capped at 10 requests per minute unless you have the High Volume add-on, and Import2 documents an average Zendesk migration speed of around 50,000 tickets per day. (developer.zendesk.com)

What to Do Next

If your migration just failed, here is the priority stack:

1. Right now: Run through the Emergency Triage Checklist above
2. Within 2 hours: Identify the root cause category (rate limits, structural mismatch, missing dependencies, tool limitation)
3. Within 4 hours: Decide rollback vs. continue based on the decision framework
4. Within 24 hours: Execute the rollback or begin a sandbox-validated recovery run
5. Within 48 hours: If recovery is not converging, get outside help before the problem compounds

The longer a partially-migrated system sits in production, the harder it gets to fix. Every new ticket created in the target is data that will not exist in the source. Every reply an agent makes in the old system is data that will not exist in the target. The drift accelerates daily.