paperclipai/paperclip · error · EnvironmentRunError

workspace_realization_failed

workspace_realization_failed

Error message

Failed to realize workspace for environment "${environment.name}" (${environment.driver}): ${err instanceof Error ? err.message : String(err)}

What it means

Failure inside realizeForRun: environmentRuntime.realizeWorkspace threw while materializing the execution workspace (local path or remote mount) for the leased environment. The driver error message is embedded, so workspace setup failures are attributed to the environment rather than the agent.

Solutions

1. Fix the workspace realization failure reported in the message (repo access, path availability), then retry.

When it happens

Trigger: Thrown at server/src/services/environment-run-orchestrator.ts:406 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-08-18). Data as JSON: /api/errors/1fadb439ad92d751. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/environment-run-orchestrator.ts:406

      try {
        const remoteCwd =
          typeof lease.metadata?.remoteCwd === "string" && lease.metadata.remoteCwd.trim().length > 0
            ? lease.metadata.remoteCwd
            : undefined;
        const workspaceRealizationResult = await environmentRuntime.realizeWorkspace({
          environment,
          lease,
          workspace: {
            localPath: executionWorkspace.cwd,
            remotePath: remoteCwd,
            mode: persistedExecutionWorkspace?.mode ?? effectiveExecutionWorkspaceMode ?? undefined,
            metadata: {
              workspaceRealizationRequest,
            },
          },
        });
        realizedWorkspaceCwd =
          typeof workspaceRealizationResult.cwd === "string" && workspaceRealizationResult.cwd.trim().length > 0
            ? workspaceRealizationResult.cwd.trim()
            : null;
        workspaceRealization = parseObject(workspaceRealizationResult.metadata?.workspaceRealization);
      } catch (err) {
        throw new EnvironmentRunError(
          "workspace_realization_failed",
          `Failed to realize workspace for environment "${environment.name}" (${environment.driver}): ${err instanceof Error ? err.message : String(err)}`,
          {
            environmentId: environment.id,
            driver: environment.driver,
            cause: err,
          },
        );
      }
    }

    const provisionCommand = workspaceRealizationRequest.runtimeOverlay.provisionCommand?.trim() ?? "";
    const realizedCwd =

View on GitHub (pinned to 3f1d897a7c)