{"record":{"id":"0e4f3f4f3b5375ac","repo":"can1357/oh-my-pi","slug":"package-import-specifier-is-excluded-by-its-p","errorCode":null,"errorMessage":"Package import \"${specifier}\" is excluded by its package imports map","messagePattern":"Package import \"(.+?)\" is excluded by its package imports map","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/extensibility/plugins/legacy-pi-compat.ts","lineNumber":1495,"sourceCode":"\t\t}\n\n\t\tif (!bestMatch || key.length > bestMatch.keyLength) {\n\t\t\tbestMatch = {\n\t\t\t\tkeyLength: key.length,\n\t\t\t\ttarget,\n\t\t\t\twildcard: specifier.slice(prefix.length, specifier.length - suffix.length),\n\t\t\t};\n\t\t}\n\t}\n\n\tif (!bestMatch || bestMatch.target === PACKAGE_IMPORT_EXCLUDED) {\n\t\treturn bestMatch?.target ?? null;\n\t}\n\treturn resolvePackageImportTarget(packageRoot, bestMatch.target, bestMatch.wildcard);\n}\nfunction packageImportPath(specifier: string, resolution: PackageImportResolution): string | null {\n\tif (resolution === PACKAGE_IMPORT_EXCLUDED) {\n\t\tthrow new Error(`Package import \"${specifier}\" is excluded by its package imports map`);\n\t}\n\treturn resolution;\n}\n\nfunction isBareExtensionDependencySpecifier(specifier: string): boolean {\n\tif (\n\t\tspecifier.startsWith(\".\") ||\n\t\tspecifier.startsWith(\"/\") ||\n\t\tspecifier.startsWith(\"#\") ||\n\t\tspecifier.startsWith(\"node:\") ||\n\t\tspecifier.startsWith(\"bun:\") ||\n\t\t/^[a-z][a-z0-9+.-]*:/i.test(specifier)\n\t) {\n\t\treturn false;\n\t}\n\tconst packageName = specifier.startsWith(\"@\") ? specifier.split(\"/\").slice(0, 2).join(\"/\") : specifier.split(\"/\")[0];\n\treturn Boolean(packageName && !isBuiltin(specifier));\n}","sourceCodeStart":1477,"sourceCodeEnd":1513,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/extensibility/plugins/legacy-pi-compat.ts#L1477-L1513","documentation":"When resolving TS `paths`-style package `imports` entries (the `#foo` subpath imports of a package.json `imports` map), a resolution can be the sentinel PACKAGE_IMPORT_EXCLUDED when the imports map explicitly excludes the specifier (e.g. null target). packageImportPath converts the sentinel into a thrown error, so callers never treat exclusion as a valid path.","triggerScenarios":"An extension's code imports a `#specifier` whose package.json `imports` map has a null/excluding entry for the best match, and the compat layer attempts to resolve it to a file path.","commonSituations":"Extension authors used `\"imports\": { \"#x\": null }` to deliberately block a subpath; a copied imports map from another tool where exclusion semantics differ; resolving internal `#` imports of a dependency whose map excludes the requested condition.","solutions":["Remove the null/excluding entry from the package.json `imports` map or point it at a real target","Import the underlying file directly instead of the excluded `#specifier`","Use a different subpath key that maps to an actual target","Check the conditions/patterns in the imports map match how the specifier is written"],"exampleFix":"// before: package.json\n{ \"imports\": { \"#config\": null } }\n// after\n{ \"imports\": { \"#config\": \"./config.ts\" } }","handlingStrategy":"try-catch","validationCode":"const pkgJson = JSON.parse(await Bun.file(packageRoot + \"/package.json\").text());\nconst entry = pkgJson.imports?.[\"#my-specifier\"];\nif (entry === null || entry === undefined) {\n\tthrow new Error(`#my-specifier is excluded or absent in imports map`);\n}","typeGuard":null,"tryCatchPattern":"try {\n\tconst p = packageImportPath(spec, resolution);\n} catch (err) {\n\tif (err instanceof Error && err.message.includes(\"excluded by its package imports map\")) {\n\t\t// fall back to direct relative import or fix the imports map\n\t}\n\tthrow err;\n}","preventionTips":["Do not use null targets in `imports` maps for specifiers your extension will import","Prefer explicit target strings for every `#` subpath you rely on","Review copied imports maps for exclusion entries before reusing them"],"tags":["package-imports","module-resolution","subpath-imports","extensions"],"backgroundTag":"package-import-excluded","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}