stride3d/stride · error · FileNotFoundException

Bundle could not be resolved

Error message

Bundle {0} could not be resolved

What it means

After probing the virtual file system for the bundle file and its dependencies, ResolveBundle throws FileNotFoundException when the bundle could not be located/resolved and throwExceptionIfNotFound was true. This means the named bundle's URL could not be determined from the mounted providers or its dependency chain.

Solutions

1. Verify the bundle file exists under the mounted virtual file system path and the name matches exactly (case included).
2. Re-run the Stride asset compiler/packager so the bundle and its dependency manifest are produced together.
3. Call with throwExceptionIfNotFound: false if a missing bundle is an acceptable, expected condition.

Example fix

// before
var url = backend.vfsUrl("misname.bundle", throwExceptionIfNotFound: true);
// after
if (!virtualFileProvider.FileExists("bundles/misname.bundle"))
    throw new FileNotFoundException("Bundle missing from deployment", "misname.bundle");

if (!virtualFileProvider.FileExists($"bundles/{bundleName}"))
    throw new FileNotFoundException($"Bundle {bundleName} missing from deployment");

try
{
    var url = backend.vfsUrl(bundleName, throwExceptionIfNotFound: true);
}
catch (FileNotFoundException)
{
    // prompt for data repair / re-download of content
    RepairDeployment();
}

When it happens

Trigger: vfsUrl(bundleName, throwExceptionIfNotFound: true) where the bundle file is not present in any mounted storage, the bundle name is misspelled, or a parent bundle references a missing dependency.

Common situations: Deploying data without copying the .bundle files; bundles produced in a newer/older build than the manifest expects; case-sensitivity mismatches on Linux; content index referencing bundles deleted at runtime.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Could not find bundle
• Could not locate native executable
• Could not locate native library
• Could not find executable to start assembly
• Package file [ ] was not found

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

Appendix: source

Thrown at sources/core/Stride.Core.Serialization/Storage/BundleOdbBackend.cs:126

                bundleUrl = await bundleResolvedHandler(bundleName);
                if (bundleUrl != null)
                    break;
            }
        }

        // Check if it has been properly resolved
        if (bundleUrl == null)
        {
            // Remove from resolved bundles
            lock (resolvedBundles)
            {
                resolvedBundles.Remove(bundleName);
            }

            if (!throwExceptionIfNotFound)
                return null;

            throw new FileNotFoundException(string.Format("Bundle {0} could not be resolved", bundleName));
        }

        // Register resolved package
        lock (resolvedBundles)
        {
            resolvedBundles[bundleName] = bundleUrl;
        }

        return bundleUrl;
    }

    /// <summary>
    /// Loads the specified bundle.
    /// </summary>
    /// <param name="bundleName">Name of the bundle.</param>
    /// <param name="objectDatabaseContentIndexMap">The object database asset index map, where newly loaded assets will be merged (ignored if null).</param>
    /// <returns>Task that will complete when bundle is loaded.</returns>
    public async Task LoadBundle(string bundleName, ObjectDatabaseContentIndexMap objectDatabaseContentIndexMap)

View on GitHub (pinned to 96fad776d2)