> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kynasmith.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MoveSpec validation issues

> Troubleshoot draft validation errors, warnings, version creation, and release readiness.

# MoveSpec validation issues

Use this page when draft validation fails or when a version is not safe to release.

## Common symptoms

* `validateDraft()` returns `ok: false`
* version creation fails after draft changes
* replay or live sessions fail because the released version is not the YAML you expected

## What to check

* Update the full draft YAML, then run validation again before versioning.
* Treat `errors` as release blockers.
* Review `warnings` before versioning even though they do not block by themselves.
* Create a new immutable version after the draft is valid.
* Release the immutable version you want runtime sessions to resolve by default.

## Catalogue and fork behavior

If you start from a public catalogue MoveSpec:

* fork it into your own project before making customer-specific changes
* validate the forked draft in your project
* release your own immutable version before runtime use

## Runtime-target mistakes

If runtime behavior does not match your draft:

* confirm you created a version after the latest draft edit
* confirm you released that version
* prefer `movespec_version_id` for deterministic replay or rollout testing

## Next references

* `/movespec/overview`
* `/api-reference/overview`