{"record":{"id":"2e00d28902e27274","repo":"dotnet/wpf","slug":"sr-format-sr-unexpectedcollectionchangeaction-args-action-2e00d2","errorCode":null,"errorMessage":"SR.Format(SR.UnexpectedCollectionChangeAction, args.Action)","messagePattern":"SR\\.Format\\(SR\\.UnexpectedCollectionChangeAction, args\\.Action\\)","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Documents/DocumentSequenceTextContainer.cs","lineNumber":604,"sourceCode":"        {\n#if DEBUG\n            this._generation++;\n#endif\n\n            if (args.Action == NotifyCollectionChangedAction.Add)\n            {\n                if (args.NewItems.Count != 1)\n                {\n                    throw new NotSupportedException(SR.RangeActionsNotSupported);\n                }\n                else\n                {\n                        object item = args.NewItems[0];\n                        int startingIndex = args.NewStartingIndex;\n\n                        if (startingIndex != _parent.References.Count - 1)\n                        {\n                            throw new NotSupportedException(SR.Format(SR.UnexpectedCollectionChangeAction, args.Action));\n                        }\n\n                        ChildDocumentBlock newBlock = new ChildDocumentBlock(this, (DocumentReference)item);\n\n                        ChildDocumentBlock insertAfter = _doclistTail.PreviousBlock;\n                        insertAfter.InsertNextBlock(newBlock);\n                        DocumentSequenceTextPointer changeStart =\n                            new DocumentSequenceTextPointer(insertAfter, insertAfter.End);\n\n                        //Update end pointer\n                        _end = new DocumentSequenceTextPointer(newBlock, newBlock.ChildContainer.End);\n\n                        if (newBlock.NextBlock == _doclistTail && newBlock.PreviousBlock == _doclistHead)\n                        {\n                            //Update start pointer for the first block\n                            _start = new DocumentSequenceTextPointer(newBlock,  newBlock.ChildContainer.Start);\n                        }\n","sourceCodeStart":586,"sourceCodeEnd":622,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Documents/DocumentSequenceTextContainer.cs#L586-L622","documentation":"In _OnContentChanged, an Add action is only valid when the new DocumentReference was appended at the end of References (startingIndex == References.Count - 1). Any other insert index breaks the sequence's linear block list, so NotSupportedException with UnexpectedCollectionChangeAction is thrown.","triggerScenarios":"Inserting a DocumentReference into DocumentSequence.References at an index other than the end (Insert at 0 or middle); raising Add with NewStartingIndex not pointing at the last item.","commonSituations":"Code that inserts a new page/document at the front of a FixedDocumentSequence; reordering References via Insert instead of Remove+Add at the end.","solutions":["Only append DocumentReferences to the end of References (use Add)","To insert earlier, rebuild the References collection: remove all, re-add in order, or create a new DocumentSequence","Avoid Insert API on References; treat it as append-only"],"exampleFix":"// before\nreferences.Insert(0, newDocRef);\n// after\nreferences.Add(newDocRef); // append only","handlingStrategy":"validation","validationCode":"if (args.Action == NotifyCollectionChangedAction.Add && args.NewStartingIndex != references.Count - 1)\n    throw new NotSupportedException(\"DocumentSequence.References only supports appending at the end\");","typeGuard":"bool IsAppend(NotifyCollectionChangedEventArgs a, ICollection c) => a.Action == NotifyCollectionChangedAction.Add && a.NewStartingIndex == c.Count - 1;","tryCatchPattern":"try { references.Insert(idx, docRef); }\ncatch (NotSupportedException) { /* rebuild sequence with docRef appended */ }","preventionTips":["Treat References as append-only; use Add, never Insert","For reordering, rebuild the whole sequence","Document the append-only contract on any collection wrapper"],"tags":["wpf","documents","collections","insert-index"],"backgroundTag":"unsupported-collection-change-action","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-22T01:17:13.364Z"}