# Diagnostics and troubleshooting

Diagnostics include code, severity, message, semantic path and, where available, XML source range. Editor highlights map the compiled structure back to XML. Embedded GraphQL locations map into document content when possible, otherwise to the containing element. Some whole-source errors have no precise range.

| Symptom | Action |
|---|---|
| journey.xml | Fix malformed XML; remove declarations, DTDs and processing instructions. |
| journey.vocabulary | Correct an unknown attribute, child, missing requirement or typed literal. |
| journey.binding | Declare the input or produce the state key before using it. |
| journey.optional-binding | Guard optional data and test the absent-value path. |
| GraphQL field/variable error | Analyze against the target schema and correct the document or typed variables. |
| Capture path error | Follow response data, or the selected item for query-pick; check aliases. |
| Next disabled | Resolve visible required fields, schema errors, unsupported capabilities or failed async work. |
| Literal template text | Use `{{ }}` interpolation only in supported prose fields: body, checklist and description. |
| Agent assistance unavailable | Configure an LLM in AiAdapters and use an assistant-capable runner; otherwise provide manual-fallback. |
| Missing resource options | Check the resource type, permissions and network connection. |

These deliberately invalid examples each fail with the named diagnostic family; they are not starter templates.

Unknown attribute:

```xml
<journey id="bad" title="Bad" unexpected="yes"><done id="done" title="Done"/></journey>
```

Forward reference:

```xml
<journey id="bad" title="Bad"><info id="intro" title="Intro"><body>{{ $.state.missing }}</body></info><done id="done" title="Done"/></journey>
```

Invalid boolean:

```xml
<journey id="bad" title="Bad"><form id="form" title="Form"><field key="name" label="Name" kind="text" required="yes"/></form><done id="done" title="Done"/></journey>
```

Forbidden DTD:

```xml
<!DOCTYPE journey><journey id="bad" title="Bad"><done id="done" title="Done"/></journey>
```

The source limit is 256 KiB. XML declarations are processing instructions and are forbidden here: begin directly with journey. Use standard XML escaping for ampersands and angle brackets in attributes/text, or CDATA for GraphQL and JSON Schema. Custom entity declarations are forbidden.

Compiler checks are layered. Fix the current error set and analyze again; a vocabulary error can prevent deeper contract or binding checks from running. Warnings may still produce an artifact and do not prove that every runtime path is safe.