Skip to main content

API Dockerfile Troubleshooting

CreatedUpdatedStatusType
2026-02-012026-02-01✅ DoneGuide

Overview​

Documents common API Dockerfile issues encountered during CI/CD deployment and their solutions.

Issues & Solutions​

1. PNPM Workspace Package Not Found​

Error:

ERR_PNPM_WORKSPACE_PKG_NOT_FOUND: "@repo/config@workspace:*" is in the dependencies
but no package named "@repo/config" is present in the workspace

Cause: Runner stage copies original package.json which references workspace packages (@repo/config, @repo/utils). In isolated runner stage, monorepo structure doesn't exist.

Solution: Create minimal package.json inline instead of copying original:

# BAD - copies workspace dependencies
COPY --from=builder /app/apps/api/package.json ./package.json
RUN pnpm add drizzle-kit postgres --prod

# GOOD - create clean package.json
RUN echo '{"name":"api"}' > package.json && \
    pnpm add drizzle-kit drizzle-orm postgres tsx

2. Container Unhealthy - wget Not Found​

Error:

Container flowershop-api is unhealthy
dependency failed to start: container flowershop-api is unhealthy

Cause: Healthcheck uses wget but Alpine doesn't include it by default:

healthcheck:
  test: ["CMD", "wget", "-q", "--spider", "http://localhost:3001/api/health"]

Solution: Install wget in runner stage:

FROM node:22-alpine AS runner
RUN apk add --no-cache wget

3. Module Format Mismatch (ESM vs CJS)​

Error: Server fails to start silently.

Cause: Build outputs CommonJS (format: ['cjs'] in tsup.config.ts), but package.json has "type": "module" which tells Node to treat .js as ES modules.

Solution: Match package.json type with build output:

# For CJS output (tsup format: ['cjs'])
RUN echo '{"name":"api"}' > package.json

# For ESM output (tsup format: ['esm'])
RUN echo '{"name":"api","type":"module"}' > package.json

4. drizzle-orm Missing​

Error:

Please install latest version of drizzle-orm

Cause: drizzle-kit requires drizzle-orm to run migrations.

Solution: Install both packages:

RUN pnpm add drizzle-kit drizzle-orm postgres tsx

5. Migration Journal Not Found​

Error:

Error: Can't find meta/_journal.json file

Cause: Mismatch between drizzle config paths:

  • Dev config: out: './drizzle/migrations'
  • Prod config: out: './drizzle'

Migrations exist at drizzle/migrations/meta/_journal.json but prod config looks at drizzle/meta/_journal.json.

Solution: Align paths in both configs and Dockerfile:

// drizzle.prod.config.ts
export default defineConfig({
  out: './drizzle/migrations',  // Match dev config
  dialect: 'postgresql',
  dbCredentials: { url: process.env.DATABASE_URL! },
});
# Copy correct path
COPY --from=builder /app/apps/api/drizzle/migrations ./drizzle/migrations

Checklist for API Dockerfile​

  • Create minimal package.json (no workspace deps)
  • Install wget for healthcheck
  • Match module format (CJS/ESM) with build output
  • Install both drizzle-kit AND drizzle-orm
  • Align migration paths between dev/prod configs
  • Copy migrations from correct source path

Code References​

  • apps/api/Dockerfile
  • apps/api/drizzle.config.ts
  • apps/api/drizzle.prod.config.ts
  • apps/api/tsup.config.ts
  • docker-compose.prod.yml