What causes "Failed to run cleanup script" in BloopAI/vibe-kanban?

Inspect backend logs for the concrete executor error behind the failure.

Failed to run cleanup script

Error message

Failed to run cleanup script

What it means

The fallback error of the RunCleanupScript action: thrown when runCleanupScript returns success:false with an error type other than 'no_script_configured' or 'process_already_running', indicating an unexpected failure while starting the cleanup script.

Source

Thrown at packages/web-core/src/shared/actions/index.ts:1194

  RunCleanupScript: {
    id: 'run-cleanup-script',
    label: 'Run Cleanup Script',
    icon: TerminalIcon,
    shortcut: 'R C',
    requiresTarget: ActionTargetType.WORKSPACE,
    isVisible: (ctx) => ctx.hasWorkspace,
    isEnabled: (ctx) => !ctx.isAttemptRunning,
    execute: async (_ctx, workspaceId) => {
      const result = await workspacesApi.runCleanupScript(workspaceId);
      if (!result.success) {
        if (result.error?.type === 'no_script_configured') {
          throw new Error('No cleanup script configured for this project');
        }
        if (result.error?.type === 'process_already_running') {
          throw new Error('Cannot run script while another process is running');
        }
        throw new Error('Failed to run cleanup script');
      }
    },
  },

  RunArchiveScript: {
    id: 'run-archive-script',
    label: 'Run Archive Script',
    icon: TerminalIcon,
    shortcut: 'R A',
    requiresTarget: ActionTargetType.WORKSPACE,
    isVisible: (ctx) => ctx.hasWorkspace,
    isEnabled: (ctx) => !ctx.isAttemptRunning,
    execute: async (_ctx, workspaceId) => {
      const result = await workspacesApi.runArchiveScript(workspaceId);
      if (!result.success) {
        if (result.error?.type === 'no_script_configured') {
          throw new Error('No archive script configured for this project');
        }

View on GitHub (pinned to 4deb7eca8f)

Solutions

Inspect backend logs for the concrete executor error behind the failure.
Run the cleanup script manually to verify it is executable and exits 0.
Verify the workspace and attempt still exist and the executor is running.
Include result.error details in the thrown message to aid future debugging.

Example fix

// before
throw new Error('Failed to run cleanup script');
// after
throw new Error(`Failed to run cleanup script: ${result.error?.message ?? 'unknown error'}`);

Defensive patterns

Strategy: try-catch

Validate before calling

// before running
if (!ctx.hasWorkspace) throw new Error('Workspace not available');
if (!ctx.project.cleanupScript) return; // handled by the no_script_configured path

Type guard

function isScriptResult(res: unknown): res is { success: boolean; error?: { type: string; message?: string } } {
  return typeof res === 'object' && res !== null && 'success' in res;
}

Try / catch

try {
  const result = await workspacesApi.runCleanupScript(workspaceId);
  if (!result.success) {
    throw new Error(`Cleanup script failed (${result.error?.type ?? 'unknown'}): ${result.error?.message ?? ''}`);
  }
} catch (err) {
  toast.error(String(err));
}

Prevention

Verify the cleanup script is executable and exits cleanly.
Review backend/executor logs after unexpected failures.
Ensure the workspace and attempt still exist before invoking.
Propagate result.error details into displayed messages.

When it happens

Trigger: workspacesApi.runCleanupScript resolving with { success: false, error: { type: <other> } } — executor spawn failures, missing workspace, script exiting abnormally, or other unclassified backend errors.

Common situations: Cleanup script with wrong shebang or missing executable permission, executor service unhealthy, workspace/attempt deleted mid-request, or disk/permission problems on the machine running the script.

Related errors

AI-assisted analysis of BloopAI/vibe-kanban@4deb7eca8f (2026-08-29). Data as JSON: /api/errors/ea1ab421ce4bd9ad. Report an issue: GitHub.