JamesNK/Newtonsoft.Json · error · ArgumentNullException

annotation

Error message

annotation

What it means

A plain ArgumentNullException(nameof(annotation)) raised by JToken.AddAnnotation when the caller passes a null annotation object. Annotations are arbitrary user objects attached to a JToken (the LINQ-to-JSON equivalent of LINQ-to-XML annotations); a null annotation is meaningless because the internal storage distinguishes a single object from an object[] and cannot represent null, so it is rejected up front.

Source

Thrown at Src/Newtonsoft.Json/Linq/JToken.cs:2553

        /// <summary>
        /// Creates a new instance of the <see cref="JToken"/>. All child tokens are recursively cloned.
        /// </summary>
        /// <param name="settings">A <see cref="JsonCloneSettings"/> object to configure cloning settings.</param>
        /// <returns>A new instance of the <see cref="JToken"/>.</returns>
        public JToken DeepClone(JsonCloneSettings settings)
        {
            return CloneToken(settings);
        }

        /// <summary>
        /// Adds an object to the annotation list of this <see cref="JToken"/>.
        /// </summary>
        /// <param name="annotation">The annotation to add.</param>
        public void AddAnnotation(object annotation)
        {
            if (annotation == null)
            {
                throw new ArgumentNullException(nameof(annotation));
            }

            if (_annotations == null)
            {
                _annotations = (annotation is object[]) ? new[] { annotation } : annotation;
            }
            else
            {
                if (!(_annotations is object[] annotations))
                {
                    _annotations = new[] { _annotations, annotation };
                }
                else
                {
                    int index = 0;
                    while (index < annotations.Length && annotations[index] != null)
                    {
                        index++;

View on GitHub (pinned to 4f73e74372)

Solutions

1. Guard the annotation with a null check before calling AddAnnotation: if (annotation != null) token.AddAnnotation(annotation);
2. Substitute a sentinel/null-object annotation instead of null if you need to record absence.
3. Fix the upstream factory to never return null annotations.

Example fix

// before
token.AddAnnotation(metadata);

// after
if (metadata != null) token.AddAnnotation(metadata);

if (annotation != null) token.AddAnnotation(annotation);

static bool IsAnnotatable(object? o) => o != null;

try { token.AddAnnotation(o); } catch (ArgumentNullException) { /* skip null */ }

When it happens

Trigger: Calling token.AddAnnotation(null) directly, or passing an expression that evaluates to null (e.g. token.AddAnnotation(maybeNullFactory()) ). Also indirectly when a generic helper forwards an unvalidated external value as an annotation.

Common situations: Storing diagnostics/metadata on tokens where the producer may legitimately return null; forgetting to null-check before annotating in a generic serialization pipeline.

Related errors

• type
• Source value must be a JToken.
• Cannot cast {0} to {1}.
• Newtonsoft.Json support for System.ComponentModel is not com
• Argument is not a JToken.

AI-assisted analysis of JamesNK/Newtonsoft.Json@4f73e74372 (2026-08-07). Data as JSON: /api/errors/2ed6107f93aceab6. Report an issue: GitHub.