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 literal 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. Schema-only routes are not enough for verify. Add x-ensures or x-requires to route schemas. See docs/getting-started.md for examples.

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. Schema-only routes are not enough for verify. Add x-ensures or x-requires to route schemas. See docs/getting-started.md for examples., 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:

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

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

# Filter by error category
cat reports/apophis/failure-<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.