# Troubleshooting a simulation

Start with the failing stage and its retained diagnostic. Installation, target
readiness, campaign admission, execution, reporting, and cleanup are separate checks.
Preserve the original evidence before changing configuration or starting new work.

## Find the failing boundary

| Symptom | Check | Next step |
| --- | --- | --- |
| Operator rejects Attack Harness | Exact shared-contract version/digest, local image identity, platform. | Select a compatible published image/package; do not edit its compatibility record. |
| Interceptor attachment fails | Live host at the selected endpoint; independent OpenAPI version/digest. | Use the compatible release and intended fresh host instance. |
| Docker/image startup fails | Local daemon, package/target architecture, macOS companion files. | Restore the complete release layout; rebuild the target for the native architecture. |
| Agent starts but cannot read data | Schema, populated seeds, grants, synthetic customer/order relationships. | Fix the blueprint assets and rebuild; startup does not run the target's migrations. |
| Retrieval returns no usable context | Document/query embedding model, dimensions, normalization, corpus population. | Generate compatible document vectors; a working embedding connector does not populate the database. |
| TLS fails | Declared hostnames, sandbox CA, correct client trust mechanism. | Configure Certifi/libpq/Node appropriately; do not disable verification. |
| Model/embedding calls fail | Independent endpoint, authentication, model allowlist, and provider access. | Check each connector separately. A present key does not prove model availability. |
| Runtime tries to download dependencies | Image contents, launch environment, tokenizer/cache requirements. | Package dependencies before isolated startup. |
| Read-only or permission errors | Actual path, mutable root, mount masking, application identity. | Use a narrow writable root and application-owned child directories. |
| Native logs missing | Real handler configuration and write path, not an assumed logging variable. | Verify the file and explicitly collect it; journals and file logs are different. |
| Bundle validation fails | Schema, target/source digest, companion file, references, declared artifact bytes. | Regenerate through native tooling; do not hand-edit exports or weaken requirements. |
| Unexpected campaign binding | Whether a probe already attached to the host process. | Retain evidence, end that host, and start a fresh instance for the actual campaign. |
| Work stops early | Time/token/operation ceilings and remaining budget, model completion allowance. | Inspect the cause and choose deliberate limits for a new run; do not assume resume. |
| Evidence unavailable/partial | Storage errors, native receipts, export status, affected sessions. | Preserve uncertainty; missing evidence is not a negative result. |

## Collect useful diagnostics

Use `operatorctl inspect --run PATH`, `operatorctl config check`, and
`operatorctl doctor` with the intended configuration. For Interceptor, use
`interceptor status SESSION_ID --json`, `interceptor logs verify SESSION_ID`, and
the session's application stdout/stderr and native file logs.

Keep run IDs, session IDs, component versions, and selected configuration together.
Do not substitute current settings for the accepted configuration of an old run.
Avoid posting real credentials or unreviewed application output into a public issue.

## Know when to start fresh

A timed-out or uncertain operation may already have changed state. Inspect the
database ledger and receipts before repeating side effects. Evidence-storage failure
can block further work in the session; fixing the disk does not retroactively create
the missing record. Keep the failed session and prepare a fresh one when needed.

Do not make the container generally writable, disable TLS checks, or add wildcard
successful service responses just to make a validation or invocation pass. Those
changes alter the environment being tested.

## Use debugging assistance

With the optional `campaign-debugging` [skill](skills.md), provide retained runs
and native evidence:

```text
Use campaign-debugging to diagnose this INTRUSIVE.AI campaign export. Identify the
failing component and cite its native evidence. Preserve uncertain outcomes and
separate configuration fixes from any claims about the target's security.
Also separate campaign execution problems from evidence about the target's
functional effectiveness when the campaign includes operational objectives.
```

Keep diagnosis of campaign execution problems separate from the results report
except where it explains coverage or evidence limitations. An agent that returns
an incorrect order status despite a working environment has produced a functional
result to assess against the campaign's objectives. A target that cannot start
because of missing configuration has an execution problem that may prevent that
assessment. Use retained evidence to distinguish them; do not assume every failure
comes from the agent or from the simulation setup.

Use the installed product's release-specific guides rather than treating another
release's flags as an available fix.
