microsoft/aspire · error · Error

AspireList must be resolved before it can be serialized…

Error message

AspireList must be resolved before it can be serialized directly. Pass it to generated SDK methods instead of calling JSON.stringify directly.

What it means

AspireList.toJSON() refuses to serialize a list whose handle has not been resolved yet. Lists must be materialized through the app host (usually by passing them to generated SDK methods); calling JSON.stringify on an unresolved AspireList hits this error because there is no wire representation yet.

Solutions

Pass the AspireList to the generated SDK method that expects it instead of serializing it yourself.
Await the list's resolution (e.g. its toResolvedJSON()/ensure-handle path) before serializing if you need its representation.
For logging, print the list's identity/state rather than JSON.stringify.
Restructure the code so plain data (not AspireList) is what gets stringified.

Example fix

// before
console.log(JSON.stringify(myList)); // throws: unresolved

// after
const resolved = await myList.toJSON(); // resolves handle first
console.log(JSON.stringify(resolved));

Defensive patterns

Strategy: validation

Validate before calling

// Resolve before serializing
const resolved = await myList.toJSON(); // or pass myList into the SDK method directly
const json = JSON.stringify(resolved);

Type guard

function isPlainSerializable(v: unknown): boolean {
  return !(v instanceof Object && "_resolvedHandle" in v && (v as { _resolvedHandle?: unknown })._resolvedHandle === undefined);
}

Try / catch

try {
  log(JSON.stringify(value));
} catch (e) {
  if (e instanceof Error && e.message.includes("must be resolved before it can be serialized")) {
    log("[unresolved AspireList]"); // log identity instead
  } else throw e;
}

Prevention

Pass AspireList values to generated SDK methods instead of stringifying them.
Await resolution before any toJSON/JSON.stringify call.
Never place Aspire builder values inside objects destined for third-party JSON APIs.

When it happens

Trigger: Calling JSON.stringify(list) on a freshly created AspireList; embedding a list in an object passed to JSON.stringify or a logging call before any SDK method resolved it; awaiting nothing and reading toJSON directly.

Common situations: Debug logging of builder values before the app model runs; caching list payloads to disk; passing config structures containing AspireLists to third-party APIs that stringify them.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/573fdbbfd4c9b21c. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.CodeGeneration.TypeScript/Resources/base.mts:813

    /**
     * Converts the list to an array (creates a copy).
     */
    async toArray(): Promise<T[]> {
        const handle = await this._ensureHandle();
        return await this._client.invokeCapability('Aspire.Hosting/List.toArray', {
            list: handle
        }) as T[];
    }

    async toTransportValue(): Promise<MarshalledHandle> {
        const handle = await this._ensureHandle();
        return handle.toJSON();
    }

    toJSON(): MarshalledHandle {
        if (!this._resolvedHandle) {
            throw new Error(
                'AspireList must be resolved before it can be serialized directly. ' +
                'Pass it to generated SDK methods instead of calling JSON.stringify directly.'
            );
        }

        return this._resolvedHandle.toJSON();
    }
}

export const AspireList = AspireListImpl;

// ============================================================================
// AspireDict<K, V> - Mutable Dictionary Wrapper
// ============================================================================

/**
 * Wrapper for a mutable .NET Dictionary<K, V>.
 * Provides object-like methods that invoke capabilities on the underlying collection.

View on GitHub (pinned to 25830f84bd)