symfony/symfony · error · RuntimeException

The importmap entry "%s" must have either a "path" or "versi

Error message

The importmap entry "%s" must have either a "path" or "version" option.

What it means

Every importmap entry needs a source: 'path' for a local file or 'version' for a remote package. If an entry has neither (only auxiliary keys like 'type' or 'entrypoint'), ImportMapConfigReader throws RuntimeException because it cannot determine where the module comes from.

Source

Thrown at src/Symfony/Component/AssetMapper/ImportMap/ImportMapConfigReader.php:75

            $isEntrypoint = $data['entrypoint'] ?? false;

            if (isset($data['path'])) {
                if (isset($data['version'])) {
                    throw new RuntimeException(\sprintf('The importmap entry "%s" cannot have both a "path" and "version" option.', $importName));
                }
                if (isset($data['package_specifier'])) {
                    throw new RuntimeException(\sprintf('The importmap entry "%s" cannot have both a "path" and "package_specifier" option.', $importName));
                }

                $entries->add(ImportMapEntry::createLocal($importName, $type, $data['path'], $isEntrypoint));

                continue;
            }

            $version = $data['version'] ?? null;

            if (null === $version) {
                throw new RuntimeException(\sprintf('The importmap entry "%s" must have either a "path" or "version" option.', $importName));
            }

            $packageModuleSpecifier = $data['package_specifier'] ?? $importName;
            $entries->add($this->createRemoteEntry($importName, $type, $version, $packageModuleSpecifier, $isEntrypoint, $data['esm'] ?? true));
        }

        return $this->rootImportMapEntries = $entries;
    }

    public function writeEntries(ImportMapEntries $entries): void
    {
        $this->rootImportMapEntries = $entries;

        $importMapConfig = [];
        foreach ($entries as $entry) {
            $config = [];
            if ($entry->isRemotePackage()) {
                $config['version'] = $entry->version;

View on GitHub (pinned to 698e28026c)

Solutions

Add a 'path' (local file) or a 'version' (remote package) to the entry.
If the entry is no longer needed, remove it entirely.

Example fix

// before: no source
'app' => ['type' => 'js', 'entrypoint' => true],

// after: local source provided
'app' => ['path' => './app.js', 'type' => 'js', 'entrypoint' => true],

Defensive patterns

Strategy: validation

Validate before calling

// Ensure every entry has exactly one source key.
foreach ($config as $name => $data) {
    if (!isset($data['path']) && !isset($data['version'])) {
        throw new \InvalidArgumentException("Entry '$name' must have either 'path' or 'version'.");
    }
}

Type guard

function entryHasSource(array $data): bool
{
    return isset($data['path']) || isset($data['version']);
}

Prevention

When adding an entry, always provide a path (local) or version (remote).
Remove entries entirely rather than leaving sourceless stubs.

When it happens

Trigger: An entry like ['type' => 'js', 'entrypoint' => true] with neither path nor version; the fallback check at lines 72-75 throws.

Common situations: Partially editing an entry and deleting the path/version line by accident; hand-authoring a new entry and forgetting the source key.

Related errors

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