Bug: Logging of non-circular references are removed by default JSON replacer function

[phipag]

Discussed in #4718

^{Originally posted by yvele November 6, 2025}
When logging an object that has multiple references to the same object (non-circular), it seems that the logger removes the duplicate reference entirely, even though it’s not circular.

cont ref = { name: "Bob" };
const obj = { ref1: ref, ref2: ref };
logger.info(obj);
// Output:
// {"ref1":{"name":"Bob"}}

You can see that ref2, even though it’s not circular, is completely removed due to the implementation of circular reference removal.

This comes from the current implementation here:

powertools-lambda-typescript/packages/logger/src/Logger.ts

Lines 739 to 772 in b387db0

	/**
	* A custom JSON replacer function that is used to serialize the log items.
	*
	* By default, we already extend the default serialization behavior to handle `BigInt` and `Error` objects, as well as remove circular references.
	* When a custom JSON replacer function is passed to the Logger constructor, it will be called **before** our custom rules for each key-value pair in the object being stringified.
	*
	* This allows you to customize the serialization while still benefiting from the default behavior.
	*
	* @see {@link ConstructorOptions.jsonReplacerFn}
	*/
	protected getJsonReplacer(): (key: string, value: unknown) => void {
	const references = new WeakSet();
	return (key, value) => {
	let replacedValue = value;
	if (this.#jsonReplacerFn)
	replacedValue = this.#jsonReplacerFn?.(key, replacedValue);
	if (replacedValue instanceof Error) {
	replacedValue = this.getLogFormatter().formatError(replacedValue);
	}
	if (typeof replacedValue === 'bigint') {
	return replacedValue.toString();
	}
	if (typeof replacedValue === 'object' && replacedValue !== null) {
	if (references.has(replacedValue)) {
	return;
	}
	references.add(replacedValue);
	}
	return replacedValue;
	};
	}

I would expect both references (ref1 and ref2) to appear in the log output, since the structure is not circular, it’s just a shared reference.

If it’s intentional, could you explain the reasoning, e.g., is the goal to enforce unique object serialization or minimize payload size?

It might also be useful to add a unit test to explicitly cover this case (or document the current behavior) to make the intention clear for contributors.

[phipag]

Posting my comment from the discussion here:

Hey @yvele, thanks for opening this discussion.

To me it seems that our default json replacer function needs to be improved here. Instead of actually detecting cycles in the object reference tree it is tracking if a reference was seen before. While this is detecting cycles correctly, it also leads to false positives like the example you shared.

While ref is the same reference, it is not introducing a cycle and therefore should not be removed.

Let me transform this discussion into an issue.

[phipag]

I will triage this issue with the TypeScript maintainers to understand next steps. Would you be interested in contributing a fix for this @yvele?

I think we need to use a proper algorithm for cycle detection, something in the likes of depth-first-search with ancestor tracking (DFS).

[svozza]

There is a good article on MDN that explains how to detect clycles in JSON that I think we can leverage here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value.

[phipag]

I believe that this algorithm will solve the issue since it tracks the chain of ancestors.

[svozza]

Yes, and another nice thing is that it doesn't just filter out the values, it also marks where exactly in the object the circular references are as part of the serialisation.

[phipag]

I also prefer that marking of "[Circular]" but do we need to consider this as a breaking change?

[dreamorosi]

Do we have any idea of whether this adds a lot of complexity or has a performance impact? Let's remember that this gets run every single time you log.

[phipag]

The while loop and .includes check are a bit problematic since it scales quadratically with the depth of the JSON object.

    while (ancestors.length > 0 && ancestors.at(-1) !== this) {
      ancestors.pop();
    }
    if (ancestors.includes(value)) {
      return "[Circular]";
    }

We should probably run a benchmark to understand the impact – although the depth of the context is usually not very deep when logging.

[leandrodamascena]

This is a curious case, and I think we should see if we can fix this for non-circular references. Just to give more context, in Python we don't need to check for a circular reference because the JSON library itself takes care of that.

without circular ref

from aws_lambda_powertools import Logger

logger = Logger()

ref = {"name": "powertools"}
extra_ref = {"ref1": ref, "ref2": ref}

logger.info(extra_ref)

{"level":"INFO","location":"<module>:8","message":{"ref1":{"name":"powertools"},"ref2":{"name":"powertools"}},"timestamp":"2025-11-07 10:52:46,967+0000","service":"service_undefined"}

with circular ref

from aws_lambda_powertools import Logger

logger = Logger()

ref = {"name": "powertools"}
extra_ref = {"ref1": ref, "ref2": ref}
# Creating a circular reference by adding a reference to extra_ref inside ref,
# which itself is referenced inside extra_ref, creating a cycle.
ref["cycle"] = extra_ref

logger.info(extra_ref)

--- Logging error ---
Traceback (most recent call last):
  File "/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py", line 1150, in emit
    msg = self.format(record)
  File "/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/logging/__init__.py", line 998, in format
    return fmt.format(record)
           ~~~~~~~~~~^^^^^^^^
  File "/private/tmp/logpy/venv/lib/python3.13/site-packages/aws_lambda_powertools/logging/formatter.py", line 209, in format
    return self.serialize(log=formatted_log)
           ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^
  File "/private/tmp/logpy/venv/lib/python3.13/site-packages/aws_lambda_powertools/logging/formatter.py", line 190, in serialize
    return self.json_serializer(log)
           ~~~~~~~~~~~~~~~~~~~~^^^^^
  File "/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/__init__.py", line 238, in dumps
    **kw).encode(obj)
          ~~~~~~^^^^^
  File "/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/encoder.py", line 200, in encode
    chunks = self.iterencode(o, _one_shot=True)
  File "/opt/homebrew/Cellar/python@3.13/3.13.2/Frameworks/Python.framework/Versions/3.13/lib/python3.13/json/encoder.py", line 261, in iterencode
    return _iterencode(o, 0)
ValueError: Circular reference detected

[svozza]

I also prefer that marking of "[Circular]" but do we need to consider this as a breaking change?

You're correct, this would be a breaking change so we can't do that.

The while loop and .includes check are a bit problematic since it scales quadratically with the depth of the JSON object.

That's a good point, although would the depth ever be large enough for this to be an issue? But to your and @dreamorosi's point, we will definitely have to measure the performance impact of any change.

[dreamorosi]

If we're saying it's a bug (which it is) and thus an unintended behavior, this is not a breaking change but a correction of error.

By implementing it, we're restoring the correct behavior.

This is how we've approached similar situations in this project across runtimes.