>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588769. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>On freshly provisioned Acquia Source instances, the Canvas CLI returns HTTP 503 for component PATCH operations (POST creation works; only PATCH update is broken). When a 503 is encountered, the agent does not investigate &mdash; it guesses a new machine name and retries with POST, then PATCHes that, gets another 503, guesses again. In a recorded session, the agent tried 15 different machine names over 3 hours: <code>site_header &rarr; eud_header &rarr; eu_nav_header &rarr; eudsite_topbar &rarr; xhdr_v2 &rarr; uni_topnav &rarr; page_header &rarr; nav_bar &rarr; site_nav</code>. Each attempt created a zombie component entity on the server. The user's response was direct: "what stupidity is bro? can't you just list all names instead of looping through your own guesses?"</p> <p>The agent had access to <code>npm run canvas:download</code> which would have listed the registered component machine names &mdash; but never used it. Two distinct failures stack:</p> <ol> <li><strong>No pre-upload registry check:</strong> the agent does not list the registry to confirm whether the intended machine name is already taken. Without this, a 503 on PATCH could mean "name conflict" or "PATCH itself is broken" and the agent cannot tell.</li> <li><strong>PATCH 503 misdiagnosed as transient:</strong> on certain Acquia Source instances PATCH for component updates returns 503 consistently &mdash; it is a platform capability gap, not a transient network error. The agent treats it as transient and retries with new names, each creating a new zombie.</li> </ol> <p>The deeper issue: component machine names are permanent in Canvas on PATCH-503 instances. Renaming is impossible. The agent must plan the machine name correctly on the FIRST upload and never retry with name variants.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <ol> <li>Provision a fresh Acquia Source instance where Canvas CLI PATCH on components returns 503.</li> <li>Run the migrate-site skill and reach component upload.</li> <li>Trigger any condition where the agent decides to rename or update an existing component (e.g., property addition that requires a fresh upload).</li> <li>Observe: agent receives 503 on PATCH, generates a new machine name, POSTs it, PATCHes it, receives 503, generates another new name, and so on.</li> <li>Confirm: 10&ndash;15 zombie component entities accumulate in the registry over hours.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p><strong>Step 1 &mdash; Add PRE-UPLOAD REGISTRY CHECK to <code>.claude/agents/component-builder.md</code> (or <code>upload-verifier.md</code>):</strong></p> <pre>PRE-UPLOAD REGISTRY CHECK (mandatory before any component upload): 1. Run: npm run canvas:download 2. Read the output to get the list of currently registered component machine names 3. Verify your intended machine name is NOT in the list 4. If it IS in the list: this component already exists on the server. - If you intend to update it: use PATCH (but see PATCH-503 warning below) - If you intend a fresh name: pick a different machine name before proceeding 5. Only after confirming the name is available: proceed with POST upload PATCH-503 WARNING: On some Acquia Source instances, PATCH returns 503 for component updates. If PATCH returns 503: - DO NOT retry with a new machine name &mdash; this creates zombie components - DO NOT try 2, 3, 5, or 15 different names - Document the issue in docs/migration/workflow/blocked.md - Continue with other components that can be uploaded - Surface the blocked component to the user with the specific error</pre><p><strong>Step 2 &mdash; Add MACHINE NAME PERMANENCE block:</strong></p> <pre>MACHINE NAME PLANNING: Canvas component machine names are permanent on some Acquia Source instances. Plan the machine name in component.yml BEFORE the first upload. Checklist before first upload: - Does the machine name follow the project naming convention? - Is this the final, permanent name (not a test or draft name)? - Have you verified via canvas:download that this name is not already taken? If any answer is NO: do not upload yet.</pre><p><strong>Step 3 &mdash; Document zombie cleanup in <code>gotchas.md</code>:</strong> after any session where PATCH-503 occurred, run <code>npm run canvas:download</code> to list zombie entities, then delete them via the Canvas UI or CLI before the next session.</p> <p><strong>Step 4 &mdash; Diagnostic scope check before concluding PATCH is broken.</strong> A missing OAuth scope (e.g., <code>canvas:js_component</code> or <code>canvas:asset_library</code> for components that reference asset library entries) can also produce 503 on PATCH. Before declaring "PATCH is broken on this instance", log the token's requested scopes and confirm the right scopes are present. The Sprint 1 scope-availability preflight (1-08) provides this data via <code>scope-availability.json</code>.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Add PRE-UPLOAD REGISTRY CHECK and PATCH-503 WARNING blocks to <code>.claude/agents/component-builder.md</code> and/or <code>upload-verifier.md</code>.</li> <li>Add MACHINE NAME PERMANENCE checklist to the same agent files.</li> <li>Add Phase 4 pre-upload note to <code>.claude/skills/migrate-site/SKILL.md</code>: "Before uploading any component, verify the machine name is not already registered (<code>npm run canvas:download</code>)."</li> <li>Document the zombie-cleanup procedure in <code>docs/migration/gotchas.md</code>.</li> <li>Wire the scope diagnostic step: read <code>scope-availability.json</code> and check <code>canvas:js_component</code>/<code>canvas:asset_library</code> are in the token's scope list before declaring PATCH broken.</li> <li>Verify on a fresh staging instance: simulate PATCH 503; agent stops after the first 503, writes <code>blocked.md</code>, and does NOT try alternative machine names. No zombie components in the registry at session end.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None. The <code>npm run canvas:download</code> command already lists the registry; no new tooling needed. The fix is wiring the existing capability into the agent's mandatory pre-upload check.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New <code>blocked.md</code> entries for unrecoverable PATCH-503 cases. New <code>gotchas.md</code> section: zombie-component cleanup procedure.</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-2-Determinism/03-P1-2-canvas-patch-503-zombie-loop.md</code> (id: P1-2)</li> <li>Session evidence (15-name zombie loop, 3 hours): <code>RESEARCH-2026-04-28/02-edu-site-mockup-ai/ce9e965e/issues-found.md</code> (ISSUE-2, ISSUE-12)</li> <li>Agent self-documented gotcha: <code>feedback_acquia_upload.md</code> (referenced in ISSUE-2)</li> <li>Pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/patterns.md</code> &sect; B1 (PATCH 503 on New Acquia Source Instances &mdash; full pattern analysis)</li> <li>Anti-pattern: <code>RESEARCH-2026-04-28/07-cross-cutting/session-anti-patterns.md</code> &sect; AP1 (Retry Storm &mdash; 15-name zombie loop is canonical)</li> <li>User feedback: <code>RESEARCH-2026-04-28/07-cross-cutting/user-feedback-corpus.md</code> &sect; Group 2 ("Have You Checked the Skills?")</li> <li>Migrate-site evolution: <code>RESEARCH-2026-04-28/05-freelygive-ai/migrate-site-evolution.md</code> ("upload-verifier always enables components one by one with public site checks after each &mdash; a direct response to recurring 503 incidents.")</li> <li>Recommended verbatim text: <code>RESEARCH-2026-04-28/99-final/migrate-site-skill-recommendations.md</code> (component-builder.md "CANVAS RUNTIME HARD RULES")</li> <li>Scope-related update: <code>RESEARCH-2026-04-28/99-final/SCOPE-REFERENCE-2026-05-01.md</code> &sect; "LOW impact &mdash; canvas:js_component" (scope hypothesis for the 503)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Is the PATCH-503 behavior specific to freshly provisioned instances, or does it affect all Acquia Source instances after some update? Affects how broadly to document the warning.</li> <li>Does <code>npm run canvas:download</code> output machine names in a parseable format? Verify on a live instance.</li> <li>How were the zombie components in the recorded session cleaned up? Was there a <code>canvas:delete</code> command, or done via the Drupal admin UI? Document the exact procedure in <code>gotchas.md</code>.</li> <li>In the recorded session: what scope was on the OAuth token when the 503 occurred? If <code>canvas:js_component</code> was missing, the scope hypothesis explains the 503 without requiring "freshly provisioned instance" as the explanation.</li> <li>Does <code>canvas:asset_library</code> scope also need to be on the token for PATCH operations on components referencing asset library entries?</li> </ul>