symfony/symfony · error · RuntimeException

Unable to find asset "%s" imported from "%s". Add it to "imp

Error message

Unable to find asset "%s" imported from "%s". Add it to "importmap.php", e.g. via the "importmap:require" command.

What it means

JavaScriptImportPathCompiler::findAssetForBareImport runs when a JS import uses a bare module specifier that is not in the root importmap. For bare specifiers ending in .css or .json, imported from a non-vendor asset and containing no '://', it calls handleMissingImport with this message, because a browser cannot resolve a bare CSS/JSON module without an importmap entry. In strict mode it throws RuntimeException.

Source

Thrown at src/Symfony/Component/AssetMapper/Compiler/JavaScriptImportPathCompiler.php:145

    {
        return 'js' === $asset->publicExtension;
    }

    private function makeRelativeForJavaScript(string $path): string
    {
        if (str_starts_with($path, '../')) {
            return $path;
        }

        return './'.$path;
    }

    private function handleMissingImport(string $message, ?\Throwable $e = null): void
    {
        match ($this->missingImportMode) {
            AssetCompilerInterface::MISSING_IMPORT_IGNORE => null,
            AssetCompilerInterface::MISSING_IMPORT_WARN => $this->logger?->warning($message),
            AssetCompilerInterface::MISSING_IMPORT_STRICT => throw new RuntimeException($message, 0, $e),
        };
    }

    private function findAssetForBareImport(string $importedModule, MappedAsset $asset, AssetMapperInterface $assetMapper): ?MappedAsset
    {
        if (!$importMapEntry = $this->importMapConfigReader->findRootImportMapEntry($importedModule)) {
            // Bare names may resolve to a valid URL at runtime, so we don't warn about them in general.
            // But the browser can only load a CSS or JSON module by bare name through an importmap entry
            // (the experimental import-attributes `with { type: '...' }` syntax aside), so a missing bare
            // `.css`/`.json` import silently does nothing - warn the user at compile time.
            if (!$asset->isVendor
                && !str_contains($importedModule, '://')
                && (str_ends_with($lowerModule = strtolower($importedModule), '.css') || str_ends_with($lowerModule, '.json'))
            ) {
                $this->handleMissingImport(\sprintf('Unable to find asset "%s" imported from "%s". Add it to "importmap.php", e.g. via the "importmap:require" command.', $importedModule, $asset->sourcePath));
            }

            return null;

View on GitHub (pinned to 3b11ffbe25)

Solutions

Register the module in importmap.php: 'php bin/console importmap:require styles.css'.
Convert the bare import to an explicit relative path that AssetMapper can map.
If the module is vendored, place it under the vendor path so it is treated as is_vendor.

Example fix

// before
import './styles.css'; // resolved to bare specifier with no importmap entry
// after
php bin/console importmap:require styles.css

Defensive patterns

Strategy: validation

Validate before calling

// ensure bare css/json imports are in the importmap before strict compile
foreach ($bareImports as $name) {
    if (null === $importMapConfigReader->findRootImportMapEntry($name)) {
        // register via importmap:require
    }
}

Type guard

function bareImportIsMapped(string $module, ImportMapConfigReader $reader): bool
{
    return null !== $reader->findRootImportMapEntry($module);
}

Prevention

Register every bare module dependency with 'php bin/console importmap:require'.
Prefer relative imports for local modules so AssetMapper resolves them without importmap.

When it happens

Trigger: Source JS (not vendor) contains import './styles.css' resolved to a bare specifier like 'styles.css' (or import 'data.json') that has no importmap.php entry, with missing_import_mode=strict. The hint points to the importmap:require command.

Common situations: Adding a CSS/JSON module import without registering it in importmap.php; converting a bundler setup to AssetMapper and forgetting to port the dependency list.

Related errors

AI-assisted analysis of symfony/symfony@3b11ffbe25 (2026-08-11). Data as JSON: /api/errors/bc626d6e3f4b793c. Report an issue: GitHub.