Problem
When deploying a scaffolded project that uses turbo run start --filter=server as the start command (e.g., on Dokploy, Railway, or any Docker-based platform), all server environment variables are undefined at runtime, even though they are correctly configured in the deployment platform.
Root Cause
Turborepo filters environment variables by default. When running turbo run start, it spawns the child process (bun run dist/index.mjs) with a sanitized environment — only variables explicitly listed in env or passThroughEnv are forwarded to the subprocess.
The generated turbo.json from turbo-generator.ts does not include a start task, so:
- There's no
start task definition for Turborepo to recognize
- Even if a
start script exists in apps/server/package.json, Turborepo doesn't pass through env vars to it
Reproduction
- Scaffold a project with
create-better-t-stack (with Turborepo + Hono server + Better Auth)
- Add
"start": "bun run dist/index.mjs" to apps/server/package.json
- Deploy using
turbo run build --filter=server and turbo run start --filter=server
- Set all required env vars in the deployment platform
- Server crashes with
❌ Invalid environment variables — every var is undefined
Expected Behavior
Environment variables set by the deployment platform should be available to the server process at runtime.
Suggested Fix
Add a start task to the turbo generator with passThroughEnv: ["*"]:
// In getBaseTasks():
start: {
dependsOn: ["build"],
cache: false,
persistent: true,
passThroughEnv: ["*"],
},
This tells Turborepo to forward all environment variables to the start task's subprocess, which is the expected behavior for production server processes.
Workaround
Manually add the start task to turbo.json:
{
"tasks": {
"start": {
"dependsOn": ["build"],
"cache": false,
"persistent": true,
"passThroughEnv": ["*"]
}
}
}
Environment
- Turborepo 2.x
- Bun runtime
- Deployed via Dokploy (Railpack-based Docker builds)
@t3-oss/env-core for env validation
Problem
When deploying a scaffolded project that uses
turbo run start --filter=serveras the start command (e.g., on Dokploy, Railway, or any Docker-based platform), all server environment variables areundefinedat runtime, even though they are correctly configured in the deployment platform.Root Cause
Turborepo filters environment variables by default. When running
turbo run start, it spawns the child process (bun run dist/index.mjs) with a sanitized environment — only variables explicitly listed inenvorpassThroughEnvare forwarded to the subprocess.The generated
turbo.jsonfromturbo-generator.tsdoes not include astarttask, so:starttask definition for Turborepo to recognizestartscript exists inapps/server/package.json, Turborepo doesn't pass through env vars to itReproduction
create-better-t-stack(with Turborepo + Hono server + Better Auth)"start": "bun run dist/index.mjs"toapps/server/package.jsonturbo run build --filter=serverandturbo run start --filter=server❌ Invalid environment variables— every var isundefinedExpected Behavior
Environment variables set by the deployment platform should be available to the server process at runtime.
Suggested Fix
Add a
starttask to the turbo generator withpassThroughEnv: ["*"]:This tells Turborepo to forward all environment variables to the
starttask's subprocess, which is the expected behavior for production server processes.Workaround
Manually add the
starttask toturbo.json:{ "tasks": { "start": { "dependsOn": ["build"], "cache": false, "persistent": true, "passThroughEnv": ["*"] } } }Environment
@t3-oss/env-corefor env validation