jackwener/OpenCLI · error · CommandExecutionError

nuget package registration leaf ${pageUrl} did not include a

Error message

nuget package registration leaf ${pageUrl} did not include an items array

What it means

This error is thrown when the NuGet registration API returns a 'page' document whose nested items property is missing or not an array. The CLI expects each registration page to contain an items array of version entries; if the response shape deviates, the CLI cannot enumerate versions and aborts with a CommandExecutionError.

Source

Thrown at clis/nuget/package.js:55

        const body = await nugetFetch(url, 'nuget package');
        const pages = Array.isArray(body?.items) ? body.items : [];
        // Each page can be inline (with `items`) or a stub that needs another fetch
        // for older packages. Inline is the common case for everything published in
        // the last few years. We follow stub pages once each — at most ~5 round-trips.
        const allEntries = [];
        for (const [pageIndex, page] of pages.entries()) {
            let pageItems = Array.isArray(page?.items) ? page.items : null;
            if (!pageItems) {
                // Stub page → fetch the leaf.
                const pageUrl = typeof page?.['@id'] === 'string' ? page['@id'] : null;
                if (!pageUrl) {
                    throw new CommandExecutionError(
                        `nuget package registration page ${pageIndex + 1} is missing @id for package "${id}"`,
                    );
                }
                const leaf = await nugetFetch(pageUrl, 'nuget package page');
                if (!Array.isArray(leaf?.items)) {
                    throw new CommandExecutionError(
                        `nuget package registration leaf ${pageUrl} did not include an items array`,
                    );
                }
                pageItems = leaf.items;
            }
            for (const it of pageItems) {
                if (!it || typeof it !== 'object' || !it.catalogEntry || typeof it.catalogEntry !== 'object') {
                    throw new CommandExecutionError(
                        `nuget package registration page ${pageIndex + 1} contains a malformed version entry`,
                    );
                }
                allEntries.push(it);
            }
        }
        if (!allEntries.length) {
            throw new EmptyResultError('nuget package', `No published versions found for NuGet package "${id}".`);
        }
        // Sort by published desc; ties broken by version string descending.

View on GitHub (pinned to 49907e53dc)

Solutions

Retry the command — transient CDN/proxy glitches often resolve on a second attempt.
Verify the package id is correct and exists on nuget.org by checking https://api.nuget.org/v3/registration5-gz-semver2/<id>/index.json directly.
Check network path: bypass corporate proxies/VPNs or whitelist api.nuget.org.
If using a custom feed, confirm it implements the NuGet Server API v3 registration schema (items array on pages).
Update the CLI in case the NuGet registration format changed and a fix was released.

Example fix

// before
const leaf = await nugetFetch(pageUrl, 'nuget package page');
if (!Array.isArray(leaf?.items)) {
    throw new CommandExecutionError(`nuget package registration leaf ${pageUrl} did not include an items array`);
}
// after
const leaf = await nugetFetch(pageUrl, 'nuget package page');
if (!Array.isArray(leaf?.items)) {
    // fall back to the raw (non-gzipped) registration endpoint before failing
    const raw = await nugetFetch(pageUrl.replace('registration5-gz-semver2', 'registration5-semver1'), 'nuget package page');
    if (!Array.isArray(raw?.items)) {
        throw new CommandExecutionError(`nuget package registration leaf ${pageUrl} did not include an items array`);
    }
    leaf.items = raw.items;
}

Defensive patterns

Strategy: type-guard

Validate before calling

const res = await fetch(`https://api.nuget.org/v3/registration5-gz-semver2/${id.toLowerCase()}/index.json`);
const body = await res.json();
const ok = Array.isArray(body?.items) && body.items.every(p => Array.isArray(p?.items));
if (!ok) throw new Error('Unexpected registration shape for ' + id);

Type guard

function hasItemsArray(page) {
  return typeof page === 'object' && page !== null && Array.isArray(page.items);
}

Try / catch

try {
  const pkg = await nugetPackage(id);
} catch (err) {
  if (String(err.message).includes('did not include an items array')) {
    // retry once, then report feed/network issue
  } else throw err;
}

Prevention

Verify package ids against search results before querying registration.
Whitelist api.nuget.org in proxies/firewalls to avoid injected HTML responses.
Pin to official NuGet v3 endpoints rather than unofficial mirrors.
Retry transient failures with backoff before surfacing the error.

When it happens

Trigger: Calling the nuget package command for a package id whose registration leaf page (fetched via nugetFetch(pageUrl, 'nuget package page')) returns JSON without an items array — e.g. a 200 response with an error body, a compressed/empty payload, a proxy or captive portal returning HTML, or a NuGet server/protocol change that renames or drops items.

Common situations: Corporate proxies or firewalls injecting HTML error pages; unofficial/private NuGet feeds (e.g. Azure Artifacts or a misconfigured source) returning a different registration schema; transient CDN glitches returning partial JSON; targeting a fake or malformed package id that resolves to an unexpected registration page.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/c06b0506f8050153. Report an issue: GitHub.