Repository navigation
A deleted or inaccessible linked app leaves clerk deploy with no working next step #568
Description
What happens
The CLI remembers which Clerk app a project folder is linked to. If that app is later deleted, or the signed-in account loses access to it, the folder still points at it, and the CLI gives no working way out:
clerk deploy(andclerk deploy status) asks Clerk for the linked app, gets "not found", and fails with a generic Platform API error. The friendlier "Clerk couldn't find this application... Runclerk linkto re-link this directory" message incommands/deploy/errors.tsisn't applied to this first lookup.- An AI agent that runs
clerk linkto fix it gets "Already linked to ()", exit code 0, and no change. In agent mode,clerk linkin an already-linked folder returns early without checking that the app still exists. - Rerunning
clerk deployfails the same way.
The commands that do work aren't mentioned anywhere in that path: clerk apps list --json, then clerk link --app <app_id> (which replaces the link), or clerk unlink --yes followed by clerk link --app <app_id>.
Who hits it
Anyone whose linked app was deleted or became inaccessible, mostly AI agents running in agent mode. A person in a terminal can get out with clerk link, which asks "Re-link to a different application?" and shows an app picker, but the error in step 1 doesn't point them there.
What the person experiences
clerk deployfails with a raw API error and no next step.- An agent that tries
clerk linkis told the folder is already linked, and loops betweenclerk deployandclerk linkuntil a person steps in. - Nothing is lost or overwritten.
How big a deal it is
- How often: rare. It needs an app deleted (or access removed) while a folder still points at it.
- How bad when it happens: medium for agents, which can't recover alone; low for people.
- Does it block them: yes, until someone runs
clerk link --app <app_id>orclerk unlink --yes. - How we know: from reading the code. Step 1's exact output hasn't been reproduced.
Proposed fix
- Map a 404 on the linked application in
clerk deployandclerk deploy statusto a clear "this app no longer exists or isn't accessible" error, with advice that works:- agent mode:
clerk apps list --json, thenclerk link --app <app_id>; - person:
clerk link, which offers to re-link.
- agent mode:
- Optionally, make agent-mode
clerk linkcheck that the saved app still exists, and give the same advice instead of "Already linked".
Where it goes: resolveLiveApplicationContext and resolveDeployState in packages/cli-core/src/commands/deploy/status.ts (the unwrapped fetchApplication calls), and the existing 404 message in packages/cli-core/src/commands/deploy/errors.ts. The optional part is in packages/cli-core/src/commands/link/index.ts.
Tests
- With a linked folder whose app returns 404, agent-mode
clerk deployandclerk deploy statusexit with the "app not found" error and adviseclerk apps list --jsonthenclerk link --app <app_id>. - Person mode advises
clerk link. - Following the agent advice ends with the folder linked to the chosen app.
Reproduce
- Link a project folder to an app with
clerk link --app <app_id>. - Delete that app in the Clerk Dashboard.
- Run
CLERK_MODE=agent clerk deploy, thenCLERK_MODE=agent clerk link, thenCLERK_MODE=agent clerk deployagain.
The first and last commands fail with an API error, and the middle one reports the folder is already linked.
Activity
Record milestone 6's decisions in the plan