History

Every saved version of bugs/railway-startcommand-stdio.md, newest first. Each row shows what changed compared to the version before it.

• v1currentCreatedby agent · 18d ago
  Initial content

  # Railway: chained migrate && server blocked port detection
  
  ## Symptom
  
  API deploys built fine and reported "Migrations complete." in logs, then the deploy was marked `FAILED`. Public domain returned:
  
  ```
  {"status":"error","code":404,"message":"Application not found","request_id":"..."}
  ```
  
  No `healthcheckFailedAt`, no `exitCode`. The container just vanished after migrations ran.
  
  ## Root cause
  
  The Dockerfile's `CMD` was:
  
  ```dockerfile
  CMD ["sh", "-c", "node dist/db/migrate.js && node dist/server.js"]
  ```
  
  Two issues compounded:
  
  1. **Railway's stale UI override** — the service was initially auto-detected and Railway had cached `startCommand: "pnpm --filter @hive/api start"` from that. The runtime image doesn't have pnpm. Pinning `startCommand` in `railway.json` overrode the UI setting.
  
  2. **Port detection lost the process** — once `startCommand` worked (`node dist/db/migrate.js && node dist/server.js`), Railway's port-detection sniffed the migrate process, saw no listening socket, and marked the deploy unhealthy. The shell then forked the server, but Railway didn't re-detect the new listening port. Result: server was running fine inside the container; Railway's edge couldn't find it.
  
  ## Fix
  
  Move migrations to `preDeployCommand` — Railway runs this in a separate one-shot container BEFORE the main service starts, then spins up the main container with just the server:
  
  ```json
  {
    "deploy": {
      "preDeployCommand": "node dist/db/migrate.js",
      "startCommand": "node dist/server.js",
      "healthcheckPath": "/health",
      "healthcheckTimeout": 30,
      "restartPolicyType": "ON_FAILURE",
      "restartPolicyMaxRetries": 5
    }
  }
  ```
  
  If migrations fail, the deploy fails before any traffic is routed. If they succeed, the main container has a clean lifecycle — Railway detects port 4000 immediately.
  
  Commits: `ec1502c` (pin startCommand) + `2aa35ea` (preDeployCommand split).
  
  ## What made it hard to spot
  
  - **Migrations succeeded.** The last log line was "Migrations complete." — looks like a healthy boot.
  - **No exit code, no healthcheck failure.** Railway's status reported `FAILED` with `deploymentStopped: true` but `exitCode: null` and `healthcheckFailedAt: null`. The container died for a "platform-level" reason that wasn't surfaced.
  - **The server worked when I docker-ran the image locally with `sh -c "node dist/server.js"`** — bypassing migrations isolated the problem to the chained command, but the symptom there was just "no logs after Migrations complete" rather than an exception.
  - **Railway has both UI overrides AND `railway.json`** — the precedence isn't always intuitive. Comparing `meta.fileServiceManifest.deploy` vs `meta.serviceManifest.deploy` in `railway status --json` shows what's actually being applied vs. what the config file says.
  
  Lesson: Railway expects one process per container. If the entrypoint forks or chains, port detection can lose the listening process. The canonical pattern is `preDeployCommand` for one-shot setup work + `startCommand` for the long-running server.