This TypeScript error occurs when configuring path aliases in tsconfig.json with incorrect syntax. Path mappings must use wildcards (*) at the beginning of the pattern to match module imports correctly. The fix involves correcting the path mapping syntax in your TypeScript configuration.
The "path mapping must start with *" error occurs when TypeScript encounters invalid path alias syntax in the `paths` configuration of tsconfig.json. Path mappings allow you to create aliases for module imports, but they must follow specific syntax rules. In TypeScript's path mapping system, wildcards (*) are used to match portions of import paths. The asterisk must appear at the beginning of the mapping pattern to properly match module names. This error typically appears when you try to use a path mapping that doesn't start with the required wildcard character. For example, if you want to map "@components/*" to "./src/components/*", the pattern must start with "*" in the mapping definition. This syntax tells TypeScript how to transform import statements during compilation.
First, examine your tsconfig.json file to see the current paths configuration:
{
"compilerOptions": {
"baseUrl": "./src",
"paths": {
// Check these mappings for syntax errors
"@components/*": ["components/*"],
"@utils/*": ["utils/*"],
"@/*": ["./*"]
}
}
}Look for any path mappings that don't start with "*". The correct syntax requires the wildcard at the beginning of the pattern on the left side.
Correct the path mapping syntax by ensuring all patterns start with "*":
// WRONG - missing * at beginning
{
"paths": {
"components": ["src/components"] // ✗ Error: doesn't start with *
}
}
// CORRECT - pattern starts with *
{
"paths": {
"@components/*": ["src/components/*"] // ✓ Correct
}
}
// WRONG - * in wrong position
{
"paths": {
"components/*/utils": ["src/components/*/utils"] // ✗ * not at beginning
}
}
// CORRECT - * at beginning
{
"paths": {
"@components/*/utils/*": ["src/components/*/utils/*"] // ✓ Correct
}
}Remember: The pattern on the left side (the import alias) must start with "*" if you want to use wildcards.
Ensure you have a baseUrl set in your compiler options, as path mappings are relative to this base:
{
"compilerOptions": {
"baseUrl": "./src", // Required for path mappings
"paths": {
"@components/*": ["components/*"] // Resolves to ./src/components/*
}
}
}Without baseUrl, TypeScript won't know where to resolve the paths from. The baseUrl should point to the directory where your source code lives.
After fixing the path mappings, test them with a simple import:
// With correct configuration:
// tsconfig.json:
// {
// "compilerOptions": {
// "baseUrl": "./src",
// "paths": {
// "@components/*": ["components/*"]
// }
// }
// }
// This should now work:
import { Button } from "@components/Button";
import { Header } from "@components/layout/Header";Run TypeScript compilation to verify:
npx tsc --noEmitIf there are no errors, your path mappings are correctly configured.
After making changes to tsconfig.json, restart the TypeScript language server in your IDE:
VS Code:
1. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
2. Type "TypeScript: Restart TS Server"
3. Select the command
WebStorm/IntelliJ:
1. Go to File → Invalidate Caches...
2. Select "Invalidate and Restart"
Other editors: Consult your editor's documentation for restarting the TypeScript language server.
This ensures your IDE picks up the new path mapping configuration.
If you're having persistent issues with path mappings, consider these alternatives:
1. Use relative imports instead:
// Instead of @components/Button
import { Button } from "../../components/Button";2. Use npm packages for path resolution:
npm install --save-dev tsconfig-pathsThen run your code with:
node -r tsconfig-paths/register dist/index.js3. Use a bundler with built-in path resolution:
- Webpack: resolve.alias in webpack.config.js
- Vite: Supports tsconfig paths natively
- esbuild: Use --alias: flag or plugins
### Understanding TypeScript Path Mapping Syntax
TypeScript's path mapping syntax follows specific rules:
1. Wildcard position: The * must be at the beginning of the pattern on the left side
2. Multiple wildcards: You can have multiple * in a pattern, but each must be at the beginning of its segment
3. BaseUrl requirement: All path mappings are resolved relative to baseUrl
4. No trailing slashes: Don't include trailing slashes in path mappings
### Common Valid Patterns:
{
"paths": {
"@components/*": ["src/components/*"], // ✓ Correct
"@utils/*": ["src/utils/*"], // ✓ Correct
"@lib/*/helpers/*": ["src/lib/*/helpers/*"], // ✓ Correct (multiple *)
"@/*": ["./*"] // ✓ Correct (root mapping)
}
}### Runtime Considerations
Remember that TypeScript path mappings only affect compilation. For runtime, you need:
1. Node.js: Use tsconfig-paths package or a bundler
2. Bundlers (webpack, Vite): Configure aliases in bundler config
3. Jest: Use moduleNameMapper in jest.config.js
### Debugging Path Mappings
Use TypeScript's trace resolution to debug:
npx tsc --traceResolution | grep "your-module"This shows how TypeScript resolves each import, including path mapping transformations.
Function expression requires a return type
Function expression requires a return type
Value of type 'string | undefined' is not iterable
How to fix "Value is not iterable" in TypeScript
Type 'undefined' is not assignable to type 'string'
How to fix "Type undefined is not assignable to type string" in TypeScript
Type narrowing from typeof check produces 'never'
How to fix "Type narrowing produces never" in TypeScript
Type parameter 'T' has conflicting constraints
How to fix "Type parameter has conflicting constraints" in TypeScript