stride3d/stride · error · ArgumentException

Package must be added to an existing PackageSession

Error message

Package must be added to an existing PackageSession

What it means

The TemplateGeneratorContext constructor requires a Package that already belongs to a PackageSession, because template generation needs the Session to operate. Passing a detached Package (Session == null) throws this ArgumentException after the null check.

Solutions

1. Create/open a PackageSession and add the package to it before constructing TemplateGeneratorContext
2. Load the package through PackageSession.LoadProject/Package loads so Session is set
3. Guard the call with `if (package.Session == null)` and attach the package first
4. In tests, build the session fixture and register the package before invoking the generator

Example fix

// before
var context = new TemplateGeneratorContext(new Package());
// after
var session = new PackageSession();
var package = new Package();
session.Packages.Add(package);
var context = new TemplateGeneratorContext(package);

if (package == null) throw new ArgumentNullException(nameof(package));
if (package.Session == null) throw new InvalidOperationException("Attach package to a PackageSession before generating templates");

bool IsPackageInSession(Package? p) => p?.Session != null;

try { var ctx = new TemplateGeneratorContext(package); } catch (ArgumentException ex) when (ex.Message.Contains("PackageSession")) { session.Packages.Add(package); retry(); }

When it happens

Trigger: Calling new TemplateGeneratorContext(package) with a package created in memory (e.g. new Package()) that was never added to a PackageSession via session.Packages.Add or SavePackage.

Common situations: Programmatic template generation scripts that construct a Package but forget to attach it to a session; tests building packages without a session; loading a package in isolation without an active editor session.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Expecting a package that is already registered in this…
• File [ ] must exist
• The target version is lower or equal to the start version.
• The upgrader has a target version higher that the current…
• The relativePath argument is null or empty

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/74992dd5f62ba26c. Report an issue: GitHub.

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/Templates/TemplateGeneratorContext.cs:28

{
    /// <summary>
    /// Initializes a new instance of the <see cref="TemplateGeneratorContext"/> class.
    /// </summary>
    /// <param name="session">The session.</param>
    public TemplateGeneratorContext(PackageSession session)
    {
        ArgumentNullException.ThrowIfNull(session);
        Session = session;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="TemplateGeneratorContext"/> class.
    /// </summary>
    /// <param name="package">The package.</param>
    public TemplateGeneratorContext(Package package)
    {
        ArgumentNullException.ThrowIfNull(package);
        if (package.Session == null) throw new ArgumentException("Package must be added to an existing PackageSession", nameof(package));
        Package = package;
        Session = package.Session;
    }

    /// <summary>
    /// Gets or sets the current session.
    /// </summary>
    /// <value>The session.</value>
    public PackageSession Session { get; private set; }

    /// <summary>
    /// Gets or sets the current package (may be null)
    /// </summary>
    /// <value>The package.</value>
    public Package? Package { get; private set; }
}

View on GitHub (pinned to 96fad776d2)