Execution workspace needs a local path before Paperclip can

Error message

Execution workspace needs a local path before Paperclip can restart it.

What it means

Thrown in the managed_restart phase of repair when the flow is about to restart configured runtime services (repairRestartsRuntimeServices is true) but ensureWorkspaceAvailable() returns falsy. Restarting services requires a usable local path for the execution workspace; the route checked existing.cwd at entry, so this fires when local-path availability fails at restart time — the record lost its cwd mid-operation or the path is no longer usable on the host. It aborts the repair after the reseed succeeded but before services come back.

Source

Thrown at server/src/routes/execution-workspaces.ts:811

                "Verified seed manifest belongs to a different workspace instance.",
              );
            }
            resolveCanonicalWorktreeSeedSource({
              registeredBaseWorkspaceCwd: baseWorkspaceCwd,
              explicitSourceConfigPath: resolveFallbackSeedSourceConfigPath(baseWorkspaceCwd),
              targetConfigPath: path.join(workspaceCwd, ".paperclip", "config.json"),
              expectedTargetInstanceId: repairSeedSource.targetInstanceId,
              manifestSource: manifest.source as { configPath?: unknown; instanceId?: unknown } | undefined,
              manifestTargetInstanceId: manifest.targetInstanceId,
            });
            await reportRepairPhase("full_reseed", "succeeded");

            await reportRepairPhase("managed_restart", "started");
            let startedServices: Awaited<ReturnType<typeof startRuntimeServicesForWorkspaceControl>> = [];
            if (repairRestartsRuntimeServices) {
              const availableWorkspace = await ensureWorkspaceAvailable();
              if (!availableWorkspace) {
                throw new Error("Execution workspace needs a local path before Paperclip can restart it.");
              }
              startedServices = await startRuntimeServicesForWorkspaceControl({
                db,
                actor: {
                  id: actor.agentId ?? null,
                  name: actor.actorType === "user" ? "Board" : "Agent",
                  companyId: existing.companyId,
                },
                issue: existing.sourceIssueId
                  ? { id: existing.sourceIssueId, identifier: null, title: existing.name }
                  : null,
                workspace: availableWorkspace,
                executionWorkspaceId: existing.id,
                config: {
                  workspaceRuntime: effectiveRuntimeConfig,
                  runtimeProvisionCommand:
                    existing.config?.runtimeProvisionCommand
                    ?? projectPolicy?.workspaceStrategy?.runtimeProvisionCommand

View on GitHub (pinned to a7e689b3c3)

Solutions

Verify the execution workspace still has its cwd and that the directory exists and is readable on the server host.
Re-check the workspace record for concurrent modifications (another operator/agent clearing the path) and restore the local path registration.
Since the database reseed already succeeded, restart services manually via the start/restart action once the path is available — you do not need a full repair re-run.
If the worktree directory was destroyed, re-create the execution workspace instead of trying to restart it.

Defensive patterns

Strategy: validation

Validate before calling

const ws = await api.getExecutionWorkspace(id);
if (!ws.cwd || !existsSync(ws.cwd)) throw new Error("Workspace local path missing/unavailable; restore it before repair with service restart.");

Type guard

function hasUsableLocalPath(ws: { cwd: string | null }): boolean {
  return typeof ws.cwd === "string" && ws.cwd.length > 0;
}

Try / catch

try { await repair(id); } catch (err) { if (/needs a local path/.test(String(err?.body?.error ?? ""))) { /* reseed already done — just fix path and call start/restart */ await restartServices(id); } else throw err; }

Prevention

Do not delete or move worktree directories while repairs are running.
Keep worktrees on storage that stays mounted for the whole repair window.
After this error, remember the database repair succeeded — only the service restart needs redoing.

When it happens

Trigger: POST repair with action=repair on a workspace whose effective runtime config defines services, where the database reseed completes but ensureWorkspaceAvailable() (called just before startRuntimeServicesForWorkspaceControl at server/src/routes/execution-workspaces.ts:811) cannot resolve an available local workspace — cwd cleared, workspace directory deleted during the repair, or availability check failing.

Common situations: Someone deletes or moves the worktree directory while a long repair is running; the workspace record was edited concurrently to remove its local path; the availability check fails because the path exists but is not accessible (permissions, unmounted disk); environments where the worktree lives on removable/network storage.

Related errors

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-21). Data as JSON: /api/errors/7f6acf88c460ac43. Report an issue: GitHub.