failure-diagnosis

# Failure Diagnosis

When diagnosing a deployment issue, work through the relevant section based on the symptom. Use the pattern tables to match log output before hypothesizing.

## Build Failure Patterns

After calling `get_deployment_logs`, scan the output for these patterns.

### Node.js

| Log pattern | Root cause | Fix |
|---|---|---|
| `ENOMEM` or `JavaScript heap out of memory` | Node ran out of memory during build | Add `NODE_OPTIONS=--max-old-space-size=4096` as build-time env var |
| `ERR_MODULE_NOT_FOUND` or `Cannot find module` | Missing dependency or wrong import path | Check `package.json` dependencies; verify the module is not dev-only if pruned |
| `error TS` followed by file path and line number | TypeScript compilation error | Read the referenced file — usually a type mismatch or missing type package |
| `sharp: Installation error` or `something went wrong installing the "sharp" package` | Missing `libvips` system dependency | Add `RUN apk add --no-cache vips-dev` (alpine) or `RUN apt-get install -y libvips-dev` (debian) before `npm install` |
| `gyp ERR!` or `node-gyp rebuild` | Native addon compilation failed — missing `python3`, `make`, or `g++` | Add build tools: `RUN apk add --no-cache python3 make g++` (alpine) or `RUN apt-get install -y python3 make g++` (debian) |
| `npm warn ERESOLVE` or `Could not resolve dependency` | Dependency version conflict | Add `--legacy-peer-deps` to install command, or fix the conflicting version ranges |
| `Error: EACCES: permission denied` | Dockerfile runs as non-root but writes to root-owned directory | Add `RUN chown -R node:node /app` before switching to non-root user |
| `next build` fails with `Module not found` for `@/` paths | Next.js path alias not resolving | Verify `tsconfig.json` `paths` and that all source files are copied before build |
| `.next/standalone` directory missing after build | `output: "standalone"` not set in `next.config.*` | Add `output: "standalone"` to Next.js config |

### Python

| Log pattern | Root cause | Fix |
|---|---|---|
| `ModuleNotFoundError: No module named` | Package not in requirements or venv not activated | Verify the module is listed in `requirements.txt` / `pyproject.toml`; check Dockerfile uses the same Python that pip installed to |
| `error: subprocess-exited-with-error` during pip install | Native extension compilation failed | Install system build deps: `RUN apt-get install -y build-essential libpq-dev libffi-dev` |
| `pg_config executable not found` | `psycopg2` needs PostgreSQL client libs | Use `psycopg2-binary` instead, or install `libpq-dev` |
| `Could not find a version that satisfies` | Pip version conflict or typo in package name | Check package name spelling and version constraints |
| `RuntimeError: uvloop does not support Windows` | Wrong base image platform | Ensure Dockerfile uses a linux base image |
| `Permission denied: '/app'` | Non-root user can't write to workdir | Add `RUN chown -R appuser:appuser /app` |

### Go

| Log pattern | Root cause | Fix |
|---|---|---|
| `cannot find module providing package` | Missing dependency or wrong module path | Run `go mod tidy` — the go.sum may be stale |
| `cgo: C compiler "gcc" not found` | CGO enabled but no C compiler in image | Either `CGO_ENABLED=0` for static builds, or install `gcc` and `musl-dev` |
| `signal: killed` during build | OOM during compilation | Increase build memory or reduce parallelism with `-p 1` flag |
| `main.go:X: undefined:` | Function or variable not exported or wrong package | Check capitalization (Go exports are uppercase) and build tags |

### Rust

| Log pattern | Root cause | Fix |
|---|---|---|
| `error[E0433]: failed to resolve` | Missing crate or wrong import path | Check `Cargo.toml` dependencies |
| `Killed` or `signal: 9` during `cargo build` | OOM during compilation — Rust builds are memory-intensive | Use `cargo build --release -j 2` to limit parallelism, or increase build memory |
| `linking with cc failed` | Missing system libraries for C bindings | Install required `-dev` packages (e.g., `libssl-dev`, `pkg-config`) |
| `error: linker cc not found` | No C linker in image | Install `build-essential` or `gcc` |

### Java

| Log pattern | Root cause | Fix |
|---|---|---|
| `java.lang.OutOfMemoryError: Java heap space` | Maven/Gradle OOM during build | Set `MAVEN_OPTS=-Xmx1024m` or `GRADLE_OPTS=-Xmx1024m` |
| `ERROR: JAVA_HOME is not set` | JDK not installed or JAVA_HOME not configured | Ensure Dockerfile uses a JDK base image (not JRE) for build stage |
| `Could not find artifact` | Missing Maven dependency or wrong repository URL | Check `pom.xml` repositories and dependency coordinates |
| `Compilation failure` with source/target version | Java source version mismatch | Match `source`/`target` in pom.xml to the JDK version in the base image |

### General Dockerfile

| Log pattern | Root cause | Fix |
|---|---|---|
| `COPY failed: file not found in build context` | Source path in `COPY` doesn't exist, or `.dockerignore` excludes it | Verify the path exists and is not in `.dockerignore` |
| `failed to solve: not found` after `FROM ... AS` | Multi-stage stage name typo or missing stage | Check that the stage name in `COPY --from=` matches a `FROM ... AS` stage |
| `manifest unknown` or `not found` in registry | Base image tag doesn't exist | Verify the image:tag exists on Docker Hub / registry |
| `executor failed running`: `No such file or directory` | Script referenced in `CMD`/`ENTRYPOINT` doesn't exist or has wrong line endings | Check the file exists in the final stage; convert CRLF to LF if built on Windows |
| `Error response from daemon: conflict` | Container name already in use | Previous deployment didn't clean up — remove the old container first |

## Container Runtime Failures

After a deployment succeeds (image built) but the container crashes or misbehaves.

### Exit Codes

| Exit code | Signal | Meaning |
|---|---|---|
| 0 | — | Clean exit — process finished normally