serialization-troubleshooting

name	serialization-troubleshooting
description	Diagnoses serialization errors and validation failures (duplicate IDs, scope/rule errors, alias conflicts, path collisions). Use when serialization validate/pull/push/watch fails or logs errors.

Serialization Troubleshooting

Triage steps

1. Reproduce with npm run dev -- serialization validate (add --json if needed).
2. If related to a specific module, use --include <name> or --exclude <name>.
3. Use npm run dev -- serialization diff to compare source/destination before a push.

Common errors and fixes

Duplicate serialized item id

• Find duplicates: rg "ID:" serialization/
• Fix by removing the duplicate file or correcting the item ID.

Path included multiple times

• Overlapping module includes. Narrow include paths or add rule exclusions.

Rule scope errors

• Wildcard rules only allow itemAndDescendants or ignored.
• alias cannot be combined with scope or wildcards.

MaxRelativePathLength too small

• Set maxRelativePathLength to >= 16.

Non‑TTY prompts

• Use --use-client-credentials or set SITECOREAI_NON_INTERACTIVE=1.
• Provide required flags instead of interactive prompts.

Validation workflow

• Fix one module at a time.
• Re-run serialization validate.
• Only proceed to push after validation is clean.