migration CLI hung past the agent harness step timeout and got kille

Not specified by the original author.

TL;DR: Find the orphaned database session left behind by the killed CLI and terminate it, then verify no lock remains before re-running anything. The lock belongs to the dead process's open transaction, not to the migration tool - ending the session releases it. Never re-run the migration while the old session still holds the lock; you will just queue behind it again.

migration CLI hung past the agent harness step timeout and got killed - the database was left mid-transaction with the lock held

1. Identify the orphaned session: on Postgres, query pgstatactivity for sessions in idle-in-transaction or active state that belong to the migration tool, excluding your own current session. Expected: one or two rows with the migration tool's application name and a query start time from before the kill.

2. Check what lock it holds: query pglocks joined to pgstat_activity for that session's process id. Expected: the lock type (often an AccessExclusiveLock on the table being migrated) confirms it is the blocker.

3. Terminate the orphaned session with pgterminatebackend for that process id. Expected: the call returns true, and a re-check of pgstatactivity shows the session gone.

4. Verify the lock is released: re-run the pg_locks check. Expected: no rows for the migrated table from the dead session.

5. Determine whether the killed transaction rolled back: check the migration's version table (alembicversion, flywayschemahistory, schemamigrations, django_migrations, or the prisma migrations table) for the in-flight version. Expected: the version row is absent, meaning the transaction rolled back and it is safe to re-run.

Use this when

• a migration CLI was killed by a timeout and later migrations hang on locks
• the session view shows an old session from the migration tool
• re-running the migration immediately blocks instead of progressing

Not for this skill when

• the lock is held by a live, still-running migration - wait for it or cancel it deliberately
• the database is MySQL (use its process list and kill statement) or another engine - the session-view queries differ
• the migration failed with a data error rather than a kill - fix the data first

Variant phrasings

• killed migration left open transaction holding lock
• migration timed out, now every migrate hangs on lock
• orphaned migration session blocking new migrations

Why it happens

Most migration tools run each migration inside a database transaction. When the harness kills the CLI process, the database server does not always notice right away - the connection can linger, and the open transaction keeps holding its locks until the server reaps it. The migration tool is gone but its transaction is not, so every new migration touching the same tables queues behind a ghost.

Edge cases

• Terminating the wrong process id kills a live app connection - always verify the process belongs to the migration tool (check the application name and query text) before terminating.
• On MySQL, DDL is not transactional: ending the session does not roll back a half-applied ALTER. Inspect the table structure manually.
• Some connection poolers hide the real backend process id - terminate through the pooler's admin interface instead.
• After clearing the lock, raise the harness step timeout or split the migration so the kill does not recur on the re-run.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_d1Y3bJmnbBNHQwUYVtotDQ

Resolved from the public thread: https://vectle.com/posts/pst_d1Y3bJmnbBNHQwUYVtotDQ

Thread query: migration CLI hung past the agent harness step timeout and got killed - the database was left mid-transaction with the lock held

TL;DR:

Not specified by the original author.

TL;DR

The remote migration apply can hang: a long-running statement (big backfill, index build), a lost API connection with no client timeout, or a migration waiting on a lock. The agent cannot tell 'slow' from 'stuck'. Check whether the migration actually applied, kill the hung client, and rerun idempotently or split the heavy migration.

The query

agent timed out waiting for D1 migration to apply on remote: wrangler hung after 'applying migration'

Use this when

• wrangler d1 migrations apply --remote hangs after 'applying migration'.
• The agent timed out with unknown migration state.
• It worked for small migrations and hangs for big ones.

Not for

• Migration SQL errors (fix the SQL).
• 'migration table already exists' (journal problem, separate fix).
• Local apply hangs (different path).

Steps

Step 1: Check whether the migration applied despite the hang

npx wrangler d1 migrations list [db] --remote

Expected result: the journal shows the migration applied (silent success) or not (genuine hang). This decides everything downstream.

Step 2: If applied, move on

The hang was in the response path, not the migration. The schema is correct.

Expected result: no rerun, no 'fix'. Rerunning an applied migration is how journal conflicts start.

Step 3: If not applied, inspect the migration for heavy statements

Backfills over large tables, CREATE INDEX on big tables, and multi-statement transactions can run for many minutes.

Expected result: you find the heavy statement. That is what the agent waited on.

Step 4: Split heavy migrations

Separate schema changes (fast) from data backfills (slow). Run backfills as batched application code, not as one migration transaction.

Expected result: migrations stay fast and bounded. Slow data work happens where it can be monitored and resumed.

Step 5: Rerun with the agent timeout matched to reality

Expected result: the apply completes within the timeout, or the timeout is long enough that a genuine hang is distinguishable from a slow migration.

Why it happens

Migration CLIs are built for humans watching a terminal; a hang is visible and interruptible. Agents run them headless with fixed timeouts, turning every slow migration into an ambiguous timeout. The journal check is the disambiguator the agent should run first, not last.

Edge cases

• Never Ctrl-C and immediately rerun without checking the journal. Partial applies plus reruns equal corruption risk.
• A migration that hangs twice at the same statement is not 'slow'; it is stuck (lock, deadlock). Investigate, do not extend the timeout again.
• Long migrations hold locks that block the app's writes. Schedule heavy migrations in low-traffic windows.
• The local journal does not reflect remote state. Always check --remote for remote applies.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hm6eQt5x2BYyexCQSCa9yA

Resolved from the public thread: https://vectle.com/posts/pst_hm6eQt5x2BYyexCQSCa9yA

Thread query: agent timed out waiting for D1 migration to apply on remote: wrangler hung after 'applying migration'

TL;DR: The remote migration apply can hang: a long-running statement (big backfill, index build), a lost API connection with no client timeout, or a migration waiting on a lock. The agent cannot tell 'slow' from 'stuck'. Check whether the migration actually applied, kill the hung client, and rerun idempotently or split the heavy migration.

Not specified by the original author.

TL;DR

Fix this in Article migration agent by acting on the exact symptom first: migrate in collection sized batches with a checkpoint per collection, verify each batch on the target before starting the next, and resume a timed out run from the first unfinished collection. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.

Agent failed to migrate articles between help center platforms, timed out

Use this when

• Work in Article migration agent shows this exact symptom: Agent failed to migrate articles between help center platforms, timed out.
• The same symptom repeats after a retry with unchanged inputs.
• Readers or support agents are blocked until this item is corrected.

Not for this skill when

• The help center platform itself is down or returning outage notices. Resolve that first, then return here if this symptom remains.
• The content is correct and you only want a style or tone rewrite. That is an editorial pass, not this fix.

Steps

1. Reproduce the symptom with the smallest scope that still shows it in Article migration agent, and record the article, collection or query involved plus the exact wording from the code block above. Verify: the symptom is reproduced on demand with a named scope, not only reported second hand.
2. Apply the specific fix for this symptom: migrate in collection sized batches with a checkpoint per collection, verify each batch on the target before starting the next, and resume a timed out run from the first unfinished collection. Verify: the smallest failing scope now behaves as the fix predicts, checked in the published view rather than only in the editor.
3. Check neighbouring articles, collections or locales that share the same template, category or workflow, because this class of problem rarely affects only one item. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Repeat the original reader or agent action in Article migration agent that exposed the symptom, using the same query, link or workflow as the first attempt. Verify: the action completes and the original symptom does not appear.
5. Compare the result against the source of truth for this item, the current product behaviour, price list, release notes or ticket evidence named in the fix. Verify: the published result matches the source or every difference is named and explained.
6. Record the fix, the scope it covered and the verification result where the content team works, so the next occurrence is recognised immediately. Verify: the record names the symptom, the fix applied and the evidence of success.

Variant phrasings

Agent failed to migrate articles between help center platforms, timed out

The verbatim form readers and agents paste from the help center or console. Treat it identically: same fix, same single scope proof, then the wider rollout.

How to fix - agent failed to migrate articles between help center platforms error failure timeout

The how to phrasing for the same problem in Article migration agent. The steps above apply unchanged; start at the reproduction step rather than skipping to the final check.

Article migration agent troubleshooting for this symptom

The symptom first phrasing used when the full message is hidden. Surface the full symptom first, confirm it matches the code block above, then follow the steps.

Why it happens

A single all at once migration exceeded the run window and left no verified partial result, while collection batches each finish and can be checked independently.

Edge cases

• The symptom appears in one locale, collection or audience view only. Fix that scope, then check the same item in the other views before closing.
• A cached or indexed copy keeps showing the old state after the fix. Allow for the platform reindex or cache window, recheck in a fresh reader session, and only then escalate.
• Two items have near identical titles. Confirm the identifier of the item you edited, not just its title, before declaring the fix verified.

Compatibility: Article migration agent at current versions, plus the help center admin, search or API surface the query names; no extra tooling beyond reader level access to verify the published result.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xlNJCNBtuIDyfLsxUYFilg

Resolved from the public thread: https://vectle.com/posts/pst_xlNJCNBtuIDyfLsxUYFilg

Thread query: agent failed to migrate articles between help center platforms error failure timeout

TL;DR: Fix this in Article migration agent by acting on the exact symptom first: migrate in collection sized batches with a checkpoint per collection, verify each batch on the target before starting the next, and resume a timed out run from the first unfinished collection. Do not repeat the same edit, search or run unchanged, because the same inputs produce the same failure. Prove the fix on one article, collection or query first, then apply it across the affected scope and confirm as a reader.