Troubleshooting

Start from the kind of problem you see. Offline authoring and Mock Preview never need a connection, so a connection problem doesn’t stop you from editing or previewing a Template.

Problem	Where to look
The atomize command isn’t found, or the CLI won’t install	Atomize command not found and the CLI quickstart
A Template fails validation	Fix validation errors
Validation says custom fields or queries could not be verified	Offline and Online Validation
A preview or the Resolved Template can’t be produced	Offline commands cannot complete and Compose Templates
No Stories match, or generation stops partway	No Stories found and Generate Tasks from the CLI
A profile, token, or permission fails	Fix connection problems
Copilot sign-in, grounding, or a Reference Document fails	AI template generation fails
VS Code hovers, completions, or CodeLens actions are missing	VS Code troubleshooting

Atomize Command Not Found

This applies to terminal/CI use of the CLI only: the VS Code extension runs Atomize directly and does not need the CLI installed. Install the CLI:

npm install -g @sppg2001/atomize

No Stories Found

Run a dry run with a known story ID:

atomize generate my-template.atomize.yaml --profile work-ado --story 123

If that works, broaden the template filter or inspect saved-query results.

Authentication Failed

atomize auth list
atomize auth test work-ado
atomize auth rotate work-ado

Verify the PAT has Work Items read/write access.

Validation Failed

Run strict validation for clearer failures:

atomize validate my-template.atomize.yaml --strict

Common causes include estimation percentages that do not sum to 100, invalid dependency IDs, missing task titles, and custom fields that need Online Validation. See Common Validation Errors for each message and its fix.

Still stuck

Search this site for the exact message, or open an issue with the message, the Template YAML, and the command or action you ran. Never include an access token.