{"record":{"id":"915b6ccf44d64044","repo":"mastra-ai/mastra","slug":"setuperror-message-the-sandbox-stays-usable-t","errorCode":null,"errorMessage":"${setupError.message}. The sandbox stays usable: this setup command is skipped for the rest of the session — retry your command, then fix the setup command in the repository settings or run it manually.","messagePattern":"(.+?)\\. The sandbox stays usable: this setup command is skipped for the rest of the session — retry your command, then fix the setup command in the repository settings or run it manually\\.","errorType":"error_code","errorClass":"SetupCommandError","httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/workspace.ts","lineNumber":609,"sourceCode":"              await runTeardownCommand(target, workdir, projectRepository.teardownCommand, {\n                timeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,\n              });\n            } catch (teardownError) {\n              console.warn('[Mastra Factory] Worktree teardown after setup failure failed', {\n                orgId: session.orgId,\n                sessionId: session.sessionId,\n                projectRepositoryId: session.projectRepositoryId,\n                error: teardownError instanceof Error ? teardownError.message.slice(-2000) : String(teardownError),\n              });\n            }\n          }\n          if (setupError instanceof SetupCommandError) {\n            // The command ran and exited non-zero — a config problem, not an\n            // infra one. Remember it so the next start recovers, and tell the\n            // agent what happens next. Infra failures (transport, clone)\n            // rethrow untouched and retry in full.\n            recordFailedSetupCommand(session.id, projectRepository.setupCommand);\n            throw new SetupCommandError(\n              `${setupError.message}. The sandbox stays usable: this setup command is skipped for the rest of the session — retry your command, then fix the setup command in the repository settings or run it manually.`,\n              setupError.code,\n            );\n          }\n          throw setupError;\n        }\n      }\n    };\n    // The session's real sandbox goes straight onto the Workspace. Providers\n    // own lazy start (`ensureRunning()` inside the first command/process op)\n    // and dead-VM self-healing, and the composed `onStart` hook runs the repo\n    // setup + credential install inside that lifecycle. Metadata-only\n    // resolutions (thread-list polling) construct but never start.\n    const sessionSandbox: SessionSandbox = requireExec(sessionEntry.sandbox);\n\n    const filesystem = new SandboxFilesystem({\n      id: `sandbox-fs:${workspaceId}`,\n      sandbox: sessionSandbox,","sourceCodeStart":591,"sourceCodeEnd":627,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/workspace.ts#L591-L627","documentation":"A user-configured repository setup command ran inside the sandbox and exited non-zero. Factory classifies this as a configuration problem (not infrastructure), records the failed command so the next session start can recover, and rethrows a SetupCommandError with guidance appended: the sandbox remains usable and the command is skipped for the rest of the session.","triggerScenarios":"The project's `setupCommand` (from repository settings) executes during workspace materialization and returns a non-zero exit code, causing SetupCommandError to be re-wrapped in createWorkspaceFactory.","commonSituations":"Setup script references a missing file, env var, or dependency; package manager install fails due to lockfile drift or private registry auth; script uses a tool not present in the sandbox image; syntax error after editing the setup command in repo settings.","solutions":["Run the setup command manually (locally or in the sandbox) to see the underlying failure and fix it in the repository settings","Check the original `setupError.message` (prefix of this message) and `setupError.code` (exit code) for the concrete cause","If a dependency was the issue, fix the lockfile/registry credentials, then retry — the next session start recovers","If the command is no longer needed, remove or simplify it in the repository settings"],"exampleFix":"// before (repo settings setupCommand)\nnpx turbo build --filter=./apps/*\n// after — pin dependencies and guard optional steps\npnpm install --frozen-lockfile && npx turbo build --filter=./apps/* || echo 'setup skipped non-fatal'","handlingStrategy":"try-catch","validationCode":"// dry-run the setup command before materializing the workspace\nconst result = await runInSandbox(session.id, projectRepository.setupCommand, { dryRun: true });\nif (result.exitCode !== 0) {\n  throw new Error(`Setup command will fail (exit ${result.exitCode}): fix it in repository settings first`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await createWorkspaceFactory(session);\n} catch (e) {\n  if (e instanceof SetupCommandError) {\n    // sandbox still usable; command skipped for the session\n    console.warn(`Setup skipped (${e.code}): ${e.message}. Fix the command or run it manually.`);\n    return workspaceWithoutSetup(e);\n  }\n  throw e; // infra failures rethrow for full retry\n}","preventionTips":["Test the repository setupCommand locally and in a fresh sandbox image before saving it","Pin dependency versions and lockfiles so installs are deterministic","Avoid env vars in setupCommand that are not guaranteed in the sandbox","Keep the setup command idempotent and fast to shrink failure surface"],"tags":["setup-command","configuration","sandbox","factory"],"backgroundTag":"setup-command-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}