apophis-fastify/docs/troubleshooting.md

# Troubleshooting Matrix

Quick reference for common failure classes, symptoms, and resolution steps.

## How to use this matrix

1. Identify the symptom or error message from your run.
2. Match it to the failure class and category.
3. Follow the resolution steps in order.

---

## Taxonomy

APOPHIS classifies failures into six categories. Lower categories take precedence when multiple failures occur.

| Category | Description | Examples |
|----------|-------------|----------|
| `parse` | Formula or config syntax errors | Unexpected token, unterminated string |
| `import` | Module resolution failures | Cannot find module, module not found |
| `load` | Config or profile loading errors | Config validation failed, profile not found |
| `discovery` | Route or plugin registration issues | Duplicate route, decorator already added |
| `usage` | CLI argument or flag errors | Unknown option, missing required argument |
| `runtime` | Behavioral contract violations | Status mismatch, missing field, equality failure |

---

## Failure Classes

### 1. Parse Error (`parse`)

**Symptoms**
- `Unexpected token` in formula output
- `Unterminated string` in x-ensures clause
- `Missing this` in operation call

**Resolution**
1. Check the route and clause index printed in the error message.
2. Verify APOSTL syntax: use `response_code(this)` not `response_code()`.
3. Ensure string literals use single or double quotes consistently.
4. Run `apophis doctor --profile <name>` to validate formulas without executing.

**Prevention**
- Run `apophis doctor --profile <name>` to validate formulas without executing.
- Enable editor support for APOSTL syntax highlighting.

---

### 2. Import Error (`import`)

**Symptoms**
- `Cannot find module '<path>'`
- `Module not found` when loading app or config

**Resolution**
1. Verify the file path exists relative to the project root.
2. Check that the module is listed in `package.json` dependencies.
3. Run `npm install` (or equivalent) to ensure node_modules is populated.
4. For ESM projects, verify the file extension matches the import (`.js` for `.ts` files).

**Prevention**
- Use absolute paths in `apophis.config.js` where possible.
- Pin dependency versions to avoid resolution drift.

---

### 3. Load Error (`load`)

**Symptoms**
- `Config validation failed`
- `Profile not found`
- `Cannot read file`

**Resolution**
1. Verify `apophis.config.js` (or `.ts`, `.json`) exists in the working directory.
2. Check that the requested profile is defined in `config.profiles`.
3. Validate config structure against the schema in `docs/cli.md`.
4. Use `apophis doctor` to list available profiles and detect config issues.

**Prevention**
- Run `apophis init` to generate a valid starter config.
- Commit config files to version control.

---

### 4. Discovery Error (`discovery`)

**Symptoms**
- `Plugin decorator already added`
- `Duplicate route registration`
- `No behavioral contracts found`

**Resolution**
1. Ensure the APOPHIS plugin is registered exactly once in the Fastify app.
2. Check for multiple imports or plugin registrations in test vs production entry points.
3. If `No behavioral contracts found`, add `x-ensures` or `x-requires` to route schemas.
4. Run `apophis doctor` to verify route discovery matches expectations.

**Prevention**
- Use a single app entry point for both production and testing.
- Add contracts during route development, not as an afterthought.

---

### 5. Usage Error (`usage`)

**Symptoms**
- `Unknown option --<flag>`
- `Missing required argument`
- `Invalid profile name`

**Resolution**
1. Run `apophis --help` to see available flags and commands.
2. Check that the profile name matches a key in `config.profiles` exactly.
3. Verify flag syntax: use `--flag value` or `--flag=value`, not `--flag value1 value2`.
4. For CI environments, use `--format json` to suppress interactive prompts.

**Prevention**
- Wrap CLI calls in package.json scripts to standardize flags.
- Validate command syntax in pre-commit hooks.

---

### 6. Runtime Behavioral Failure (`runtime`)

**Symptoms**
- `Expected 200, observed 404`
- `Missing field: <name>`
- `Equality mismatch`
- `Response time exceeded`

**Resolution**
1. Read the `Expected` / `Observed` / `Why this matters` sections in the failure output.
2. Use the printed `Replay` command to reproduce the failure locally.
3. Check the request/response context in the artifact for debugging details.
4. For status code mismatches: verify the handler logic and preconditions.
5. For missing fields: ensure the handler returns the expected shape.
6. For temporal failures (`previous()`): stabilize app state or use deterministic test data.

**Prevention**
- Use `apophis verify --seed <number>` for deterministic runs.
- Run `apophis observe` in CI to catch drift before it becomes a failure.
- Keep test data isolated and reset between runs.

---

## Artifact-Driven Triage

Every failure produces an artifact JSON file. Use it for deep triage:

```bash
# Inspect the artifact
cat reports/apophis/verify-<timestamp>.json | jq '.failures[0]'

# Replay the exact failure
apophis replay --artifact reports/apophis/verify-<timestamp>.json

# Filter by error category
cat reports/apophis/verify-<timestamp>.json | jq '.failures | map(select(.category == "runtime"))'
```

---

## CI-Specific Guidance

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| Tests pass locally but fail in CI | Environment drift or nondeterministic data | Pin seed with `--seed`, isolate external deps |
| `npx apophis` not found in CI | Package not installed or bin path wrong | Use `npm ci` and verify `package.json` bin field |
| Artifact not written in CI | Missing `artifactDir` or permission issue | Set `--artifact-dir ./artifacts` in CI config |
| Slow CI runs | Too many routes or deep presets | Use `--profile quick` or `--routes` filter |
| JSON output unreadable | Machine mode lacks human formatting | Use `--format json-summary` for concise CI logs |

---

## Getting More Help

1. Run `apophis doctor` for automated diagnostics.
2. Check `docs/cli.md` for command reference.
3. Review `docs/getting-started.md` for first-run guidance.
4. Inspect the artifact file for full request/response context.