{"record":{"id":"c3bb859d950bcc11","repo":"mastra-ai/mastra","slug":"sandbox-provider-sandbox-provider-did-not-exp-c3bb85","errorCode":null,"errorMessage":"Sandbox provider \"${sandbox.provider}\" did not expose a public URL for port ${port}. Make sure the port is declared when constructing the sandbox (e.g. `ports: [${port}]`).","messagePattern":"Sandbox provider \"(.+?)\" did not expose a public URL for port (.+?)\\. Make sure the port is declared when constructing the sandbox \\(e\\.g\\. `ports: \\[(.+?)\\]`\\)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/engine.ts","lineNumber":81,"sourceCode":"  // 1. Start (providers handle create-or-resume by identity, e.g. sandbox name).\n  logger.info(`Starting ${sandbox.provider} sandbox...`);\n  await sandbox.start?.();\n\n  if (!supportsNetworking(sandbox)) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" does not support networking (public port URLs), ` +\n        `which is required for sandbox deploys.`,\n    );\n  }\n  if (!sandbox.executeCommand) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" does not support executeCommand, which is required for sandbox deploys.`,\n    );\n  }\n\n  const url = await sandbox.networking.getPortUrl(port);\n  if (!url) {\n    throw new Error(\n      `Sandbox provider \"${sandbox.provider}\" did not expose a public URL for port ${port}. ` +\n        `Make sure the port is declared when constructing the sandbox (e.g. \\`ports: [${port}]\\`).`,\n    );\n  }\n\n  // Default the remote dir to $HOME/mastra-app — home directories persist\n  // across snapshot stop/resume (unlike /tmp), so wakes find the app intact.\n  const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);\n\n  const mergedEnv = { ...env };\n  if (studio && mergedEnv.MASTRA_STUDIO_PATH === undefined) {\n    mergedEnv.MASTRA_STUDIO_PATH = `${remoteDir}/studio`;\n  }\n\n  // 2. Upload the build output as a tarball and extract it in the sandbox.\n  logger.info(`Uploading build output from ${dir}...`);\n  const tarball = await createTarball(dir);\n  logger.debug(`Tarball size: ${(tarball.length / 1024 / 1024).toFixed(2)} MB`);","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/engine.ts#L63-L99","documentation":"After capability checks pass, deployToSandbox requests the provider's public URL for the deploy port. If getPortUrl returns null/undefined — typically because the port wasn't declared at sandbox construction — the deploy cannot continue and this error is thrown.","triggerScenarios":"Calling deployToSandbox while the provider's networking.getPortUrl(port) returns null: the requested port is not in the sandbox's declared `ports`, or the provider hasn't provisioned a URL for it.","commonSituations":"Deploying on a custom PORT without declaring it in ports at sandbox creation; provider allocates URLs lazily and the port was declared after sandbox creation; typo'd port number mismatch between deploy options and sandbox config.","solutions":["Declare the port at sandbox construction: `ports: [port]`","Make the port passed to deployToSandbox match a declared port","Recreate the sandbox so newly declared ports are provisioned","Log/inspect all provider-exposed URLs to confirm the expected port exists"],"exampleFix":"// before\nconst sandbox = new Sandbox({ ports: [] });\nawait deployToSandbox(sandbox, { port: 8788 });\n// after\nconst sandbox = new Sandbox({ ports: [8788] });\nawait deployToSandbox(sandbox, { port: 8788 });","handlingStrategy":"validation","validationCode":"if (!ports.includes(port)) {\n  throw new Error(`Port ${port} must be declared at sandbox construction: ports: [${port}]`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await deployToSandbox(sandbox, { port });\n} catch (err) {\n  if (String(err).includes('did not expose a public URL')) {\n    console.error(`recreate the sandbox with ports: [${port}]`);\n  } else throw err;\n}","preventionTips":["Declare all deploy ports in the sandbox constructor, never after","Keep port values in a single shared constant","Recreate sandboxes when changing the declared ports list"],"tags":["sandbox","networking","port-url","deployment"],"backgroundTag":"port-not-exposed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}