symfony/symfony · warning · RuntimeException

Unable to find asset "%s" referenced in "%s". The file "%s"

Error message

Unable to find asset "%s" referenced in "%s". The file "%s" does not exist.

What it means

CssAssetUrlCompiler rewrites url() and @import references in CSS to point at digested public paths of other mapped assets. When Path::join resolves the reference but getAssetFromSourcePath() returns null and the target file is not on disk, it emits this message via handleMissingImport(). Behavior depends on missing_import_mode: 'warn' (default) logs and leaves the URL unchanged, 'strict' throws RuntimeException, 'ignore' is silent.

Source

Thrown at src/Symfony/Component/AssetMapper/Compiler/CssAssetUrlCompiler.php:111

            $asset->addDependency($dependentAsset);
            $relativePath = Path::makeRelative($dependentAsset->publicPath, \dirname($asset->publicPathWithoutDigest));

            return $matches[1][0].'"'.$relativePath.'"'.($matches[3][0] ?? '');
        }, $content, -1, $count, \PREG_OFFSET_CAPTURE);
    }

    public function supports(MappedAsset $asset): bool
    {
        return 'css' === $asset->publicExtension;
    }

    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),
        };
    }
}

View on GitHub (pinned to 698e28026c)

Solutions

1. Confirm the referenced file exists at the resolved path with exact case (check on a case-sensitive filesystem).
2. If the file exists but is outside a mapped directory, add its directory to asset_mapper.paths.
3. Correct the relative path in the CSS url()/@import.
4. Temporarily set missing_import_mode to 'strict' in dev to surface every missing reference as an error.

Example fix

/* before: wrong folder name */
background: url(../img/bg.png);

/* after: correct relative path */
background: url(../images/bg.png);

// Pre-scan a CSS file's url()/@import targets and verify each resolves under a mapped path.
use Symfony\Component\Filesystem\Path;
preg_match_all(CssAssetUrlCompiler::ASSET_URL_PATTERN, $css, $m, PREG_OFFSET_CAPTURE);
foreach ($m[2] as $ref) {
    $target = Path::join(dirname($cssSourcePath), $ref[0]);
    if (!is_file($target)) {
        throw new \RuntimeException("Missing CSS reference: $ref[0] (resolved to $target)");
    }
}

// In strict mode, collect all missing references without aborting the whole build.
$missing = [];
try {
    $compiler->compile($content, $asset, $mapper);
} catch (\Symfony\Component\AssetMapper\Exception\RuntimeException $e) {
    $missing[] = $e->getMessage();
    // continue with next file, report $missing at the end
}

When it happens

Trigger: Compiling a .css asset whose url()/@import match resolves to a source path; getAssetFromSourcePath($resolvedSourcePath) is null and is_file($resolvedSourcePath) is false (the 'does not exist' branch). The message is then routed through handleMissingImport().

Common situations: Referenced image/font/CSS was deleted; wrong relative path; typo; file gitignored so absent after clone/deploy; case-sensitivity mismatch between macOS dev and Linux prod; recent rename not propagated to CSS.

Related errors

• The asset "%s" cannot be found in any asset map paths.
• AssetMapper support cannot be enabled as the AssetMapper com
• Asset with public path "%s" not found.
• Failed to compile JavaScript import paths in "%s". Error: "%
• Unable to find asset "%s" imported from "%s".

AI-assisted analysis of symfony/symfony@698e28026c (2026-08-06). Data as JSON: /api/errors/b8af76271bfb68fa. Report an issue: GitHub.